Improve Skill

Transforms session learnings, analysis documents, and discovered patterns into structured skill improvements.

When to Use

• •User has notes/documents with learnings from a deep work session
• •User wants to update an existing skill with new patterns discovered
• •User wants to create a new skill from accumulated knowledge
• •User says "improve skill", "update skill", "add to skill", "skill learnings"

Process

1. Gather Context

Identify the inputs:

• •Learnings source: Session notes, analysis docs, conversation history
• •Target skill: Existing skill to improve, or create new
• •Scope: What categories of learnings (patterns, anti-patterns, workflows, reference data)

If the user references a past session (e.g. "the session where we did X", "the session on branch Y"), you'll need to locate and read the session transcript from disk. See SESSION-FILES.md for how to find and read Claude Code session files.

If the user hasn't specified a target skill, ask:

• •Is this for an existing skill? Which one?
• •Or should this become a new skill?

2. Read Existing Skill (if improving)

Read the target skill's files:

ls -la <skill-directory>/
cat <skill-directory>/SKILL.md
# Read any additional reference files

Understand the current structure before proposing changes.

3. Extract Learnings

From the source documents, identify:

4. Decide on Structure

For small additions (< 50 lines):

• •Add directly to SKILL.md in appropriate section

For substantial additions (50-200 lines):

• •Create new section in SKILL.md with summary
• •Consider separate reference file if content is lookup-oriented

For large additions (> 200 lines):

• •Create separate .md file (e.g., MODULES.md, PATTERNS.md)
• •Add brief reference in SKILL.md pointing to the new file
• •Use progressive disclosure pattern

5. Apply Updates

Follow these principles:

1. •Preserve existing structure - Add to existing sections when possible
2. •Use consistent terminology - Match the skill's existing voice/terms
3. •Keep SKILL.md scannable - Move reference tables to separate files
4. •Add context on when to use - New content should explain its trigger
5. •Update description if needed - If scope changed, update frontmatter

6. Verify

After making changes:

# Check file exists and is valid
cat <skill-directory>/SKILL.md | head -20

# Verify frontmatter is valid YAML
# - name: lowercase, hyphens, max 64 chars
# - description: non-empty, max 1024 chars

# Check for broken internal links
rg "\[.*\]\(.*\.md\)" <skill-directory>/

Output Format

Present changes as:

1. •Summary - What was added/changed
2. •Rationale - Why this structure was chosen
3. •Files modified - List of files changed
4. •Skill description update - If the description should change

Guidelines

• •Be concise: Only add what Claude doesn't already know
• •Prefer tables: For reference data, classifications, mappings
• •Use examples: Concrete over abstract
• •One level deep: Reference files should link from SKILL.md, not from each other
• •Test mentally: Would this help Claude in a future session?

Creating New Skills

If creating a new skill rather than improving existing:

1. •

   Choose location:

   • •~/.claude/skills/<name>/ - Personal, all projects
   • •.claude/skills/<name>/ - Project-specific
2. •

   Create directory and SKILL.md:

   bash

   mkdir -p <location>/<skill-name>
   

3. •

   Write SKILL.md with:

   markdown

   ---
   name: <lowercase-with-hyphens>
   description: <what it does and when to trigger, max 1024 chars>
   ---
   
   # <Skill Title>
   
   <Brief description>
   
   ## When to Use
   <Trigger conditions>
   
   ## Process
   <Step-by-step workflow>
   
   ## Guidelines
   <Key principles>
   

4. •

   Add reference files as needed for large content blocks