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.

45 stars 4 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pjt222/agent-almanac --skill refactor-skill-structure
Manual install
git 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-structure

Personal 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.
Read the full skill on GitHub

Details

Skill name
refactor-skill-structure
Path
i18n/caveman-lite/skills/refactor-skill-structure/SKILL.md
License
MIT
Repo updated
18 November 2026

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

45

pjt222/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.

Software DevelopmentIn 1 list

Adaptic

45

pjt222/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.

OtherIn 1 list

Add Puzzle Type

45

pjt222/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.

Testing & QAIn 1 list

Remote Viewing

45

pjt222/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

Software DevelopmentIn 1 list

Probe Feature Flag State

45

pjt222/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

Software DevelopmentIn 1 list

Review Codebase

45

pjt222/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.

Software DevelopmentIn 1 list

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.