Skill Updater

Skill Updater

Overview

This skill evolves skills during project usage by adding references, improving explanations, and documenting discovered patterns—all while respecting each skill's contract. It reads a skill's "Skill Contract" section to understand what can change and what must remain stable.

When to Use This Skill

Use this skill when:

• Discovering a pattern or technique that should be added to a skill
• Finding better ways to explain existing skill concepts
• Encountering edge cases not covered by current skill documentation
• Creating project-specific examples worth preserving
• Identifying confusing areas that need clarification

Important: Only use with skills that have a "Skill Contract" section (created by skill-contract-generator).

Workflow

Step 1: Identify Update Opportunity

Recognize when a skill could be improved:

During project work:

• "This workflow isn't documented in the skill"
• "This edge case should be mentioned"
• "A better example would clarify this"
• "This pattern keeps coming up"

Ask yourself:

• Is this improvement general enough for the skill?
• Or is this project-specific (belongs in CLAUDE.md)?

Rule of thumb:

• If useful for other projects → update skill
• If project-specific → document in CLAUDE.md or LOG.md

Step 2: Read Skill Contract

Locate and read the skill's contract:

Contract location:

• In the skill's SKILL.md file
• Section titled "## Skill Contract"

What to extract:

• Stable elements: What cannot be changed
• Mutable elements: What can evolve
• Update rules: What's allowed, what requires review, what's prohibited
• Knowledge extraction rules: What to look for

If no contract exists:

• Use skill-contract-generator to create one first
• Or proceed conservatively (only add references, no SKILL.md changes)

Step 3: Classify Update Type

Determine what kind of update is needed:

Type 1: Add Reference File

• New patterns, workflows, or examples
• Goes in references/ directory
• Usually allowed without review

Type 2: Improve SKILL.md

• Clarify confusing wording
• Add examples to existing sections
• Fix typos or formatting
• Check contract: may need review

Type 3: Add Script

• Automation or validation tool
• Goes in scripts/ directory
• Check contract: often requires review

Type 4: Optimize Structure

• Reorganize sections
• Add new sections
• Usually requires review or is prohibited

Step 4: Verify Against Contract

Check if the update is allowed:

Allowed without review:

• Typically: reference files, examples, typos
• Check contract's "Allowed without review" list
• Proceed to Step 5

Requires review:

• Typically: SKILL.md structure changes, new sections
• Check contract's "Requires review" list
• Ask user: "This update requires review per the skill contract. Proceed?"
• If yes → Step 5, if no → Stop

Prohibited:

• Check contract's "Prohibited" list
• If prohibited: inform user, suggest alternative
• Example: "Contract prohibits changing workflow steps. Consider adding to references/ instead?"

Step 5: Prepare Update

Create the update content:

For reference files:

# [Topic Name]

## Context

[Why this reference is needed]

## Pattern/Workflow/Example

[Detailed content]

## Usage

When to use this pattern:
- [Scenario 1]
- [Scenario 2]

## Related

- Main skill: [section references]
- Other skills: [if applicable]

For SKILL.md updates:

• Read current content around update point
• Draft new content that matches existing style
• Preserve formatting and structure
• Keep additions concise

For scripts:

• Follow SkillOS code style (see CLAUDE.md)
• Add docstrings
• Test before adding

Step 6: Apply Update

Execute the update:

Adding reference file:

1. Create file in references/ with descriptive name
2. Add entry to SKILL.md "Resources" section (if exists)
3. Use clear filename: references/[topic]-[type].md

Updating SKILL.md:

1. Read current SKILL.md
2. Find insertion point
3. Insert new content
4. Preserve existing formatting
5. Write updated SKILL.md

Adding script:

1. Create script in scripts/ directory
2. Add to Resources section
3. Document usage in SKILL.md

Step 7: Document the Update

Record what changed and why:

Update LOG.md:

## YYYY-MM-DD HH:MM

### [REFACTOR] Updated [skill-name] skill

**Context:** [Why this update was needed]

**What Changed:**
- Added `references/[filename].md` documenting [topic]
- [OR] Clarified [section] in SKILL.md
- [OR] Added `scripts/[filename].py` for [purpose]

**Impact:**
- Skill now covers [new scenario]
- Better guidance for [use case]

**Contract compliance:**
- Update type: [allowed without review / reviewed and approved]
- Contract section: [which part of contract allowed this]

**Related:**
- Project: [current project name]
- Skill: `.claude/skills/[skill-name]/`

Optionally update skill's contract:

• If update reveals new patterns for extraction
• If boundaries should be refined
• Use skill-contract-generator to update

Step 8: Verify and Commit

Ensure update maintains skill quality:

Checklist:

• Contract rules followed
• Existing content preserved
• Formatting consistent
• New content is general (not project-specific)
• References are clear and useful
• No broken links or references

Test if possible:

• For scripts: run and verify output
• For workflow changes: walk through mentally
• For examples: check they're correct

Commit:

• Use git to commit skill update
• Reference in commit message: which skill, why updated

Update Patterns

Pattern 1: Adding Project Workflow

Scenario: Discovered project-specific workflow that uses the skill

Action:

1. Create references/[project-type]-workflow.md
2. Document the workflow
3. Add pointer from main SKILL.md if generally useful

Example: Adding references/monorepo-git-workflow.md to git-workflow skill

Pattern 2: Clarifying Confusion

Scenario: User confused by existing explanation

Action:

1. Identify confusing section
2. Add example or clarification
3. Test with fresh perspective

Example: Adding example to project-logger for complex log entries

Pattern 3: Edge Case Documentation

Scenario: Encountered edge case not covered

Action:

1. Add to existing section if short
2. Or create references/edge-cases.md if many
3. Include workaround or solution

Example: Adding conflict resolution edge case to git-workflow

Pattern 4: Template Enhancement

Scenario: Template missing useful section

Action:

1. Check contract: template changes often need review
2. If allowed: add section with [OPTIONAL] marker
3. Update template documentation

Example: Adding optional security section to CLAUDE.md template

Important Notes

Respect Skill Contracts

• Contracts exist to preserve skill identity
• Breaking contracts fragments knowledge
• When in doubt, add to references/ not SKILL.md

General vs. Project-Specific

Add to skill if:

• Useful across multiple projects
• Generalizable pattern
• No project-specific details

Keep in project if:

• Specific to this codebase
• One-off solution
• Tied to project context

Decision heuristic:

• Would 3+ other projects benefit? → Skill
• Unique to this project? → CLAUDE.md or LOG.md

When to Create New Skill vs. Update

Update existing skill when:

• Natural extension of current scope
• Fills gap in existing coverage
• Same domain and user base

Create new skill when:

• Different domain or use case
• Would make existing skill too complex
• Distinct workflow or purpose

Accumulating Knowledge

Updates should accumulate wisdom:

• Each update adds value
• Preserve historical examples (don't replace)
• Build comprehensive coverage over time

Resources

This skill operates by reading and modifying other skills' files. It doesn't require its own references or scripts, but relies on:

• Skill contracts (created by skill-contract-generator)
• Project LOG.md (to document updates)
• Git (to version control changes)

Skill Contract

Stable: 8-step workflow, contract compliance checking, safety verifications Mutable: Update patterns, decision heuristics, examples, edge case documentation Update rules: See references/contract.md for detailed rules

Full contract specification in references/contract.md