Refactor Skill Structure
Refactor an over-long or poorly structured SKILL.md by extracting examples to references/EXAMPLES.md, splitting compound procedures, and reorganizing sections for progressive disclosure. Use when a skill exceeds the 500-line CI limit, when code blocks dominate the skill body, when a procedure step contains multiple unrelated operations, or after a content update pushed the skill over the line limit.
Install
npx skills add pjt222/agent-almanac --skill refactor-skill-structuregit clone --depth 1 https://github.com/pjt222/agent-almanac.git /tmp/agent-almanac
mkdir -p ~/.claude/skills
cp -r /tmp/agent-almanac/i18n/caveman-lite/skills/refactor-skill-structure ~/.claude/skills/refactor-skill-structurePersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Refactor Skill Structure Refactor a SKILL.md that has exceeded the 500-line limit or developed structural problems. This skill extracts extended code examples to `references/EXAMPLES.md`, splits compound procedures into focused sub-procedures, adds cross-references for progressive disclosure, and verifies the skill remains complete and valid after restructuring. ## When to Use - A skill exceeds the 500-line limit enforced by CI - A single procedure step contains multiple unrelated operations that should be separate steps - Code blocks longer than 15 lines dominate the SKILL.md and could be extracted - The skill has accumulated ad-hoc sections that break the standard six-section structure - After a content update pushed the skill over the line limit - A skill review flagged structural issues that go beyond content quality ## Inputs - **Required**: Path to the SKILL.md file to refactor - **Optional**: Target line count (default: aim for 80% of the 500-line limit, i.e., ~400 lines) - **Optional**: Whether to create `references/EXAMPLES.md` (default: yes, if extractable content exists) - **Optional**: Whether to split into multiple skills (default: no, prefer extraction first) ## Procedure ### Step 1: Measure Current Line Count and Identify Bloat Sources Read the skill and create a section-by-section line budget to identify where the bloat is.
Details
- Skill name
refactor-skill-structure- Repository
- pjt222/agent-almanac
- Path
i18n/caveman-lite/skills/refactor-skill-structure/SKILL.md- License
- MIT
- Repo updated
- 18 November 2026
- Listed in
- BehiSecc/awesome-claude-skills
FAQ
What does the Refactor Skill Structure skill do?
Refactor an over-long or poorly structured SKILL.md by extracting examples to references/EXAMPLES.md, splitting compound procedures, and reorganizing sections for progressive disclosure. Use when a skill exceeds the 500-line CI limit, when code blocks dominate the skill body, when a procedure step contains multiple unrelated operations, or after a content update pushed the skill over the line limit.
How do I install the Refactor Skill Structure skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add pjt222/agent-almanac --skill refactor-skill-structure. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Refactor Skill Structure popular?
It lives in pjt222/agent-almanac, which has 45 GitHub stars and 4 forks, and is included in 1 curated skill list.
Related skills
Adapt Architecture
45pjt222/agent-almanac
Execute structural metamorphosis using strangler fig migration, chrysalis phases, and interface preservation. Covers transformation planning, parallel running, progressive cutover, rollback design, and post-metamorphosis stabilization for system architecture evolution. Use when assess-form has classified the system as READY for transformation, when migrating from monolith to microservices, when replacing a core subsystem while dependents continue operating, or when any architectural change must be gradual rather than big-bang.
Adaptic
45pjt222/agent-almanac
Master skill composing the 5-step synoptic cycle for panoramic synthesis across multiple domains. Orchestrates meditate, expand-awareness, observe, awareness, integrate-gestalt, and express-insight into a coherent process that produces unified understanding rather than sequential compromise. Use when a problem genuinely spans 3+ domains and the interactions between domains matter more than depth in any one, when sequential analysis feels like compromise rather than integration, or before major architectural decisions affecting multiple stakeholders.
Add Puzzle Type
45pjt222/agent-almanac
Scaffold a new puzzle type across all 10+ pipeline integration points in jigsawR. Creates the core puzzle module, wires it into the unified pipeline (generation, positioning, rendering, adjacency), adds ggpuzzle geom/stat layers, updates DESCRIPTION and config.yml, extends the Shiny app, and creates a comprehensive test suite. Use when adding a completely new puzzle type to the package or following the 10-point integration checklist to ensure nothing is missed end-to-end.
Remote Viewing
45pjt222/agent-almanac
AI intuitive exploration for approaching unknown codebases, problems, or systems without preconceptions. Adapts the Coordinate Remote Viewing protocol to AI investigation: cooldown (clear assumptions), staged data gathering (raw signals → dimensional → analytical), AOL management (separating observations from premature labels), and structured review. Use when investigating an unfamiliar codebase with unknown architecture, debugging a problem where premature hypotheses could mislead, exploring a domain with limited context, or when previous attempts have been led astray by assumptions and "begi
Probe Feature Flag State
45pjt222/agent-almanac
Probe the runtime state of a named feature flag in a CLI binary. Covers the four-pronged evidence protocol (binary strings, live invocation, on-disk state, platform cache), the four-state classification (LIVE / DARK / INDETERMINATE / UNKNOWN), gate-vs-event disambiguation, conjunction-gate handling, and skill-substitution scenarios where a flag appears DARK but the capability is delivered by other means. Use when verifying whether a documented or inferred capability has rolled out, when auditing dark-launched features, or when a prior probe's conclusions need refreshing against a new binary ve
Review Codebase
45pjt222/agent-almanac
Multi-phase deep codebase review with severity ratings and structured output. Covers architecture, security, code quality, and UX/accessibility in a single coordinated pass. Produces a prioritized findings table suitable for direct conversion to GitHub issues via the create-github-issues skill.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.