# Skill Refiner

> Improve and validate existing Claude Code skills for clarity, efficiency, and production readiness. Use when: refining skills, improving skill structure, validating against best practices, reducing token usage, consolidating references, checking production readiness, or applying the 80% rule. Takes imperfect existing skills and elevates them to quality standards.

- Skill: `full-stack-biz/skill-refiner` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add full-stack-biz/skill-refiner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/full-stack-biz/skill-refiner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: full-stack-biz (https://skillmd.com/u/full-stack-biz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/full-stack-biz/skill-refiner

---


# Skill Refiner

Systematically improve and validate Claude Code skills while preserving functionality and following established patterns.

## Quick Start

**Step 0: Detect Predating Context (Escape Hatch)**

Check conversation history:
- User already provided the skill file or shared code?
- User already described the problem/issue?
- User is actively discussing a skill's problems?

**IF PREDATING CONTEXT EXISTS** → Offer escape hatch immediately:

```
questions: [
  {
    question: "I've reviewed the skill and context you provided. How would you like to proceed?",
    header: "Interview Style",
    options: [
      {
        label: "Infer from context",
        description: "I'll infer refinement needs from what you shared. Skip detailed interview (faster)"
      },
      {
        label: "Define explicitly",
        description: "I'll ask you to explicitly define improvement areas and goals (full interview)"
      }
    ],
    multiSelect: false
  }
]
```

Then route:
- **"Infer from context"** → Skip to BATCH 2 with context-tailored prompts
- **"Define explicitly"** → Full BATCH 1 + BATCH 2

**IF NO PREDATING CONTEXT** → Continue to Step 1

**Step 1:** Use AskUserQuestion to ask: **"What skill do you want to work on?"** (open-form text input)

**Step 2:** Use AskUserQuestion with **predefined options** to ask:

```
questions: [
  {
    question: "What would you like to do with this skill?",
    header: "Action",
    options: [
      {
        label: "Refine",
        description: "Improve clarity, structure, efficiency, token usage, or organization"
      },
      {
        label: "Validate",
        description: "Check if it's production-ready (tool scoping, completeness, error handling, trigger phrases)"
      }
    ],
    multiSelect: false
  }
]
```

**Step 3:** Route based on their selection:

- **If "Refine"** → Proceed to **Core Workflow: Refinement** (you'll be asked BATCH 1 + BATCH 2 interview questions during the workflow)
- **If "Validate"** → Skip interview, go directly to **Core Workflow: Validation**

## Core Workflow: Refinement

**When user requests refinement:**

1. **Locate the skill (MANDATORY first step)**
   - Search current project first: `skills/skill-name/`, `.claude/skills/skill-name/`
   - If not found in project → Check user-space: `~/.claude/skills/skill-name/`
   - If found in user-space → WARN: "This affects all projects. Continue?"
   - If in cache (`~/.claude/plugins/cache/`) → REFUSE: "That's an installed copy (read-only)"
   - If not found anywhere → ASK: "Where should I find this skill?"

### Requirements Interview (Progressive Disclosure - One Batch at a Time)

After locating the skill, **interview to gather what they want improved** using AskUserQuestion with proper options.

**🔴 BATCH 1: Refinement Focus** (Progressive AskUserQuestion - ask one at a time):

#### Question 1: What aspects need improvement?

```
questions: [
  {
    question: "What aspects need improvement?",
    header: "Focus Areas",
    options: [
      { label: "Clarity", description: "Make instructions clearer, remove jargon, improve examples" },
      { label: "Efficiency", description: "Reduce token usage, consolidate references, optimize content" },
      { label: "Structure", description: "Reorganize sections, improve flow, better grouping" },
      { label: "User Interaction UX", description: "Convert free-form interactions to AskUserQuestion patterns, improve workflows" }
    ],
    multiSelect: true
  }
]
```

#### Question 2: What specific problems are you seeing?

```
questions: [
  {
    question: "What specific problems are you seeing?",
    header: "Key Issues"
  }
]
```

(Examples: "Instructions are hard to follow", "References scattered and redundant", "Too many nested sections")

#### Question 3: What would success look like?

```
questions: [
  {
    question: "What would success look like?",
    header: "Success Metric"
  }
]
```

(Examples: "Clearer workflow", "Fewer token costs", "Production-ready with error handling")

#### Question 4: Any areas to exclude or preserve as-is?

```
questions: [
  {
    question: "Any areas to exclude or preserve as-is?",
    header: "Scope Limits"
  }
]
```

(Examples: "Keep the validation gates", "Don't change tool scoping")

After gathering ALL responses, document approved scope and proceed to BATCH 2.

**🟢 BATCH 2: Implementation Details** (Use AskUserQuestion with predefined options)

**ROUTING NOTE:**
- If user chose **"Infer from context"** in escape hatch → Skip BATCH 1, come straight here
- If user chose **"Define explicitly"** → Proceed after BATCH 1 responses
- **Context-Aware Prompts:** When inferring from context, tailor questions to specific issues mentioned (e.g., "I saw token usage issues in references. Consolidate them?" vs generic "Should we consolidate?")

```
questions: [
  {
    question: "Should we consolidate related reference files to reduce scattered content?",
    header: "References",
    options: [
      { label: "Yes", description: "Merge related files for clarity" },
      { label: "No", description: "Keep current structure" }
    ],
    multiSelect: false
  },
  {
    question: "Should we also validate against production standards?",
    header: "Production Validation",
    options: [
      { label: "Yes", description: "Check error handling, tool scoping, security" },
      { label: "No", description: "Skip production validation" }
    ],
    multiSelect: false
  },
  {
    question: "Should we add testing & validation patterns (evaluation framework, test patterns, quality gates)?",
    header: "Testing & Validation",
    options: [
      { label: "Yes", description: "Add evaluation framework and quality gates" },
      { label: "No", description: "Skip testing patterns" }
    ],
    multiSelect: false
  }
]
```

After gathering ALL responses, document approved scope and proceed.

---

2. **Load workflow reference**
   - Review `references/refinement-workflow.md` for the complete refinement workflow with all preservation gates and validation phases

3. **Identify consolidation opportunities (BEFORE changes)**
   - List all files in `references/` directory with line counts
   - Group by topic (what do they cover?)
   - Flag potential merges (2-4 files on same topic → 1 consolidated file)
   - ASK: "Should we consolidate these files? Saves N lines, improves clarity"
   - Only proceed if operator approves

4. **Apply preservation gates (CRITICAL - four gates, in order)**
   - **GATE 1**: Content Audit - list ALL existing content, classify as core (80%+) or supplementary (<20%)
   - **GATE 2**: Capability Assessment - will changes impair execution? If YES → cannot delete, only migrate
   - **GATE 3**: Migration Verification - before moving content, verify destination exists and is complete
   - **GATE 4**: Operator Confirmation - deletions require explicit approval, migrations auto-approved

5. **Make changes (following movement pattern)**
   - CREATE/UPDATE destination FIRST (new file, updated section)
   - LINK - update SKILL.md pointers to new destination
   - DELETE old source (only after links verified)
   - Never delete first; always: CREATE → LINK → DELETE

6. **Validate result (seven phases)**
   - Phase 1: File Inventory - list structure before/after
   - Phase 2: Read All - load complete content, verify no gaps
   - Phase 3: Frontmatter - check required metadata (name, description)
   - Phase 4: Body Content - verify <500 lines, 80% rule applied, clarity improved
   - Phase 5: References - confirm all linked files exist and are complete
   - Phase 6: Tools - review allowed-tools scoping against skill needs
   - Phase 7: Testing - verify activation with real-world trigger phrases

## Core Workflow: Validation

**When user requests validation:**

1. **Locate the skill** (same as refinement step 1)

2. **Run validation phases (seven phases, systematic)**
   - **Phase 1: File Inventory** - List all files: SKILL.md, references/, scripts/, assets/
   - **Phase 2: Read All** - Load complete skill content (frontmatter, body, all references)
   - **Phase 3: Frontmatter Check** - Verify required fields: `name`, `description`
   - **Phase 4: Body Content** - Check: <500 lines? 80% rule applied? Clear procedural instructions?
   - **Phase 5: References** - Verify: all linked files exist? No orphaned files? One level deep only?
   - **Phase 6: Tool Scoping** - Review `allowed-tools` against actual tool usage. Principle of least privilege applied?
   - **Phase 7: Testing** - Verify activation: does description include trigger phrases? Will Claude recognize real requests?

3. **Generate validation report**
   - Structure: Status (✅ Production Ready / ⚠️ Needs Review / ❌ Issues Found)
   - Detail: Findings from all seven phases
   - Recommendations: Specific improvements if issues found
   - Priority: Which issues are critical vs. advisory

## Key Rules (Non-Negotiable)

### The 80% Rule (Content Distribution)
- Will Claude execute this in 80%+ of skill activations? → **STAYS in SKILL.md**
- Will Claude execute this in <20% of cases? → **CAN MOVE to references/**
- Uncertain? → **DEFER to operator; keep in SKILL.md by default**

### Movement Pattern (for content changes)
```
SEQUENCE (never violate order):
1. CREATE/UPDATE destination file(s) with merged content
2. LINK - Update SKILL.md pointers to new destination(s)
3. DELETE old source (only after links verified and tested)

NEVER: DELETE → LINK → CREATE (creates broken links and lost content)
```

**Visual flow:**

```
    ❌ WRONG                              ✅ CORRECT

    DELETE old source                     CREATE destination
            │                                     │
            ▼                                     ▼
    LINK to new location                  LINK pointers
            │                                     │
            ▼                                     ▼
    CREATE destination                    DELETE old source
    (broken links!)                       (safe, links verified)
```

### Preservation Gates (Four Gates, In Order)
1. **Content Audit** - List ALL existing content. Classify using **the 80% rule**: core content (used in 80%+ of activations) vs. supplementary (<20%). Example: release-process uses standard workflow every time → core; monorepo coordination is rare → supplementary. See `references/80-percent-rule.md` for full decision framework.
2. **Capability Assessment** - Will changes impair execution? If YES → cannot delete, only migrate
3. **Migration Verification** - Before moving, verify destination complete. NO GAPS
4. **Operator Confirmation** - Deletions require explicit approval. Migrations auto-approved

### Scope Rules (Where to Work)
✅ **PREFERRED** - Project paths (search first):
- `skills/skill-name/` in plugin projects
- `.claude/skills/skill-name/` in any project

⚠️ **CONDITIONAL** - User-space (only if not in project):
- `~/.claude/skills/skill-name/` - WARN: "Affects all projects"
- Requires explicit user confirmation before editing
- Offer to copy to project instead

❌ **FORBIDDEN** - Never edit (REFUSE IMMEDIATELY):
- `~/.claude/plugins/cache/*` (installed plugins - read-only)
- Any path containing `/cache/` (always read-only)

## Reference Guide

### Refining for Clarity
Remove jargon, improve examples, restructure for flow
→ `references/ask-user-question-patterns.md` for interaction patterns
→ `references/content-guidelines.md` for description improvement
→ `references/anti-patterns.md` for what NOT to do

### Refining for Efficiency (Token Usage)
Apply 80% rule, consolidate references, optimize content
→ `references/80-percent-rule.md` for content distribution decisions
→ `references/skill-workflow.md` for detailed framework
→ `references/movement-pattern.md` for safe migration procedure

### Refining for Structure
Reorganize sections, improve grouping, better information flow
→ `references/refinement-workflow.md` for unified workflow with gates
→ `references/movement-pattern.md` for safe content relocation
→ `references/advanced-patterns.md` for archetype structures

### Preserving Functionality (Safety Gates)
Never break existing behavior, never delete without knowing where content goes
→ `references/preservation-rules.md` for what NEVER gets cut
→ `references/refinement-guardrails.md` for safe patterns
→ `references/movement-pattern.md` for CREATE → LINK → DELETE sequence

### Validating Quality
Check production readiness, tool scoping, completeness
→ `references/validation-checklist.md` for comprehensive assessment
→ `references/production-patterns.md` for error handling and team patterns
→ `references/allowed-tools.md` for tool scoping validation

### Understanding Refinement Fully
Complete workflow with all phases and preservation gates
→ `references/refinement-workflow.md`

## Pro Tips

**Finding skills efficiently:**
- Project-scoped skills in `skills/` or `.claude/skills/` (search project first)
- User-space skills in `~/.claude/skills/` (only if not in project)
- Use `Glob` pattern: `**/SKILL.md` to find all skills in project
- Never search cache paths; they're read-only copies

**Wizard pattern (progressive disclosure):**
- Ask one question, wait for response, then ask next
- Build context step-by-step (avoid form-like multi-questions)
- Document operator's choices; proceed only with approved scope

**Production patterns:**
- Detailed logging of changes made (helps with version tracking)
- Validation scripts provide confidence before deployment
- Error handling for edge cases (missing files, malformed YAML, etc.)

**Preservation principle:**
- Refinement improves existing functionality; it never reduces it
- When in doubt about deletion, ask operator first
- Movement is safer than deletion (can always link back)

## Common Scenarios

**Scenario 1: "Simplify this skill"**
→ Focus on clarity: restructure sections, improve examples, simplify language
→ Identify redundancy in references, suggest consolidation
→ Verify 80% rule for SKILL.md body content

**Scenario 2: "Reduce token usage"**
→ Apply **80% rule:** identify supplementary content used in <20% of cases (e.g., error handling for rare failure modes) that can move to references
→ Keep core content (80%+ usage) in SKILL.md (e.g., standard error handling patterns)
→ Consolidate related reference files
→ Verify activation doesn't suffer from moved content
→ See `references/80-percent-rule.md` for decision examples

**Scenario 3: "Improve user interaction UX"**
→ Audit all AskUserQuestion calls (max 4 options, progressive disclosure)
→ Convert free-form instructions to predefined AskUserQuestion options where applicable
→ Ensure questions follow wizard pattern (ask → wait → ask, not forms)
→ Verify descriptions are clear and help users make good choices
→ Check for >4 options violations (split into multiple AskUserQuestion batches)
→ See `references/ask-user-question-patterns.md` for patterns and decision trees

**Scenario 3.5: "Improve reference quality"**
→ Audit every reference link: does it provide context about what agents will find?
→ Pattern check: [Core knowledge] + `See `references/file.md` for [edge cases/depth]`
→ Flag orphaned links (bare links with no context): "This reference might not get loaded because agents don't know what's in it"
→ Offer: "Let's add context snippets so agents load references intentionally, not out of uncertainty"
→ Improves token efficiency: references only load when truly needed

**Scenario 4: "Check if this skill is production-ready"**
→ Run full validation phases (all 7 phases)
→ Check: error handling, tool scoping, clear trigger phrases, comprehensive testing
→ Flag missing production patterns (error handling, validation scripts, security review). See `references/production-patterns.md` for team patterns.
→ Generate detailed report with findings and recommendations

**Scenario 5: "Offer to help during skill work"**
→ Detect user is working with skills (reading SKILL.md, editing references, etc.)
→ Offer: "I can help refine this skill (clarity, efficiency) or validate it. Want me to?"
→ If yes, use appropriate workflow above

## Notes

**Token efficiency:** Skill-refiner itself should stay <500 lines (this body content). Reference files contain detailed workflows—loaded on-demand only.

**Auto-activation signals:** Watch for user requests containing: "refine", "improve", "make clearer", "reduce tokens", "validate", "check if ready", "is this production-ready", or when user is actively modifying skill files.

**Error handling:** If skill files can't be located, are malformed, or have structural issues, report specific problems and suggest solutions rather than failing silently.

**Version tracking:** Track changes made to skills during refinement (which files modified, what changed). Helps users understand impact of refinements.