/update-skill

/update-skill - Update Existing Skills from Project Knowledge

Refresh one or more skills by diffing their current content against what the project actually does today. Pulls from .context/knowledge/, live source files, and dependency manifests to keep skills accurate and actionable.

When to Run

• After /learn accumulates several entries for a domain a skill covers
• After a library version upgrade that a skill documents
• After conventions drift and the skill no longer reflects reality
• Periodically (e.g., after every few features) to keep skills sharp

$ARGUMENTS

Parse the invocation:

• /update-skill [name] — update a specific skill by directory name (e.g., testing-conventions)
• /update-skill --stale — scan all skills, identify drift, report, ask which to update
• /update-skill --all — run --stale check then update every stale skill

Process

Single skill: /update-skill [name]

1. Validate the skill exists at skills/[name]/SKILL.md. If not, stop and list available skills.

2. Measure baseline: wc -c skills/[name]/SKILL.md and record the byte count.

3. Diff current state — compare skill content against project reality:

   • testing-conventions: Read actual test files. Check framework (jest/pytest/rspec), file naming, describe/it structure, mocking approach, assertion style. Note mismatches with what the skill claims.
   • api-conventions: Read actual route/controller files. Check HTTP method conventions, error response shape, auth middleware placement, validation patterns.
   • Library skills (postgres, redis, python-backend, etc.): Read package.json, requirements.txt, Gemfile, or equivalent. Compare installed version against the version the skill documents. Flag if major version differs.
   • Any skill: Check .context/knowledge/ for entries that belong in this skill's domain — see step 4.

4. Gather new content from knowledge sources:

   • Scan .context/knowledge/LEARNINGS.md for entries related to this skill's domain
   • Scan .context/knowledge/libraries/ for relevant library knowledge files
   • Read .context/patterns/CODE_PATTERNS.md and ANTI_PATTERNS.md for patterns that fit this skill's scope
   • If this is a library skill and the version changed: use Context7 to check for API changes between the documented version and the installed version

5. Draft the update:

   • Merge new content into the existing skill structure — preserve section headings and archetype
   • Remove content that contradicts what the project actually does (document the removal reason in the report)
   • Preserve all existing content that is still accurate
   • If populating a previously empty skeleton: follow the same population approach /init uses (read real project files, fill sections with concrete, greppable examples)
   • Token budget: aim for ~40 lines in SKILL.md. If new content would push past that, extract detail to skills/[name]/REFERENCE.md and link from SKILL.md

6. Review pass: Delegate to reviewer agent with:

   • The original skill content
   • The proposed updated content
   • The source evidence gathered in steps 3-4

   Reviewer checks:

   • No valid existing content was lost
   • New content is accurate, concrete, and actionable (not vague)
   • Still within the ~40-line token budget
   • The description frontmatter field still accurately describes what the skill covers
   • Structural archetype (sections, frontmatter) is intact

7. Apply reviewer-approved changes by writing the updated SKILL.md.

8. Measure after: wc -c skills/[name]/SKILL.md. Report delta.

9. Report:

   Skill updated: skills/[name]/SKILL.md
   Before: [N] bytes | After: [N] bytes | Delta: [+/-N]
   
   Changes:
   - Added: [what was added and why]
   - Removed: [what was removed and why]
   - Unchanged: [what was preserved]
   
   Sources used: [list of .context/ files or source files consulted]
   

---

Stale scan: /update-skill --stale

1. Enumerate all skills in skills/*/SKILL.md.

2. Classify each skill:

   • Framework-level (auth-security, context-system, sequential-thinking, prompt-efficiency, mcp-tools, context7-docs, git-workflow, deployment-cicd): skip — these document general best practices, not project specifics.
   • Project-specific (testing-conventions, api-conventions, and any user-created skills): check for drift.
   • Library skills (postgres, redis, python-backend, react-frontend, ruby, database-migrations, knowledge-base, google-workspace, postgres-mcp, puppeteer): check installed version vs documented version.

3. For each project-specific skill: run the diff check from step 3 of the single-skill flow (lightweight — just flag mismatches, don't gather full new content yet).

4. For each library skill: read the relevant manifest (package.json, requirements.txt, Gemfile, pyproject.toml) and compare the installed version to what the skill documents.

5. Report staleness:

   ## Skill Staleness Report
   
   | Skill                  | Type            | Status  | Drift Details                          |
   |------------------------|-----------------|---------|----------------------------------------|
   | testing-conventions    | project-specific| STALE   | Skill says jest, project uses vitest   |
   | api-conventions        | project-specific| OK      | No drift detected                      |
   | postgres               | library         | STALE   | Skill: v14, installed: v16             |
   | redis                  | library         | OK      | Version matches                        |
   | auth-security          | framework       | SKIPPED | Framework-level, not project-specific  |
   

6. Ask: "Which skills would you like to update? List names or say 'all stale'."

7. Update each confirmed skill using the single-skill flow above.

---

Update all: /update-skill --all

Run the --stale scan, then update every skill flagged as STALE without prompting per-skill. Present a combined report at the end.

---

Rules

• Never modify framework-level skill content (e.g., auth-security OWASP rules, react-frontend component patterns, git-workflow branching rules). These encode general best practices, not project specifics.
• Only update project-specific content: testing-conventions, api-conventions, and any user-created or empty skills.
• For library skills: update the documented version and any API usage notes that changed — do not rewrite the entire skill.
• Always preserve the skill's structural archetype (frontmatter, section headings). Never remove sections — only clear stale content within them.
• Token budget (~40 lines for SKILL.md) is enforced. Overflow goes to skills/[name]/REFERENCE.md.
• Reviewer agent must approve before any changes are written.
• Report before/after byte counts for every updated skill.
• If a skill is an empty skeleton, populating it is the same operation — treat it as a full update from scratch, sourcing content from real project files.
• Do not update skills when the project has no source files in that skill's domain — report "no project content found" instead.

User Input

$ARGUMENTS