skill-updater

name	skill-updater
description	Updates skills during project work according to their contracts. Adds references, improves explanations, and refines examples while respecting skill boundaries. Use when discovering patterns, encountering edge cases, or finding better ways to explain skill concepts. Works with skills that have Skill Contracts defined by skill-contract-generator.

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