extend-skillset
Use when the stack profile names a tool no installed skill covers, or the user asks for a new skill. Authors one in the house style, audit-first and profile-aware, into the project's .claude/skills or
SKILL.mdskills/core/extend-skillset/SKILL.md
GitHubExtend Skillset
Turns "no skill covers X" into a skill that fits the set. Template and checklist: skill-template.md. House style: this repo's CONTRIBUTING.md.
1. Audit (change nothing)
cat .claude/stack-profile.md 2>/dev/null
ls .claude/skills 2>/dev/null; ls skills/*/ 2>/dev/null | head -80
grep -rli "<tool or topic>" .claude/skills skills 2>/dev/null | head
Answer three questions before writing anything:
- Is there already a skill that covers it (even partly)? Extend that one; do not add a twin.
- Is the gap a procedure with a trigger ("when X, do Y")? If it is only a fact, add it to a reference file or
_shared/instead. - Is the stack stable enough to encode? A tool in the "Assess" ring of tech-radar.md gets a short skill with a warning, not a full one.
2. Decide
| Situation | Action |
|---|---|
| Existing skill covers it | Edit it; add the case; stop. |
| Fact only | Add a rule to the nearest reference file; stop. |
| New procedure | Continue. |
Choose the destination (ask once with AskUserQuestion, recommended first):
- Project (Recommended):
.claude/skills/<name>/— private to this repo, zero release cost. - Upstream:
skills/<catalogue>/<name>/in this plugin repo — for skills useful to others. Needs registration by the maintainer (README, CHANGELOG, validator).
3. Research the stack live
Follow version-protocol.md. For each tool the skill touches: latest stable version, current install command, config keys, breaking changes of the last major. Read the official docs page, not a blog. Write each verified fact with its source into the reference file, and into the catalogue's _shared/stack-versions.md when one exists. If you cannot verify a fact, mark it unverified and say so in the skill.
4. Write the skill
Use skill-template.md. Requirements:
- Folder
<name>kebab-case, verb-first (set-up-x,configure-x,build-x,audit-x);nameequals the folder. descriptionstarts withUse when, one sentence, at most 300 characters, names the trigger situation, not the topic.- Body: numbered, audit-first, idempotent: Audit → Decide → Detect track → Install only the missing → Generate seams → Wire → Verify (exact command and expected output). At most about 180 lines.
- Step 1 reads
.claude/stack-profile.mdand branches on it; if absent, it detects from the repo and asks one question only when detection is ambiguous and the answer changes the output (then suggestsset-up-stack-profile). - Reference file: each rule as
## Rule:with Why, How to apply, optional Anti-example; ends with## When to deviate. - Link to the shared contracts instead of restating them: engineering-principles.md, security-baseline.md, logging-contract.md, observability.md.
- Code snippets compile against the current API. One canonical pattern, not a menu.
- Plain prose; none of: simply, just, seamless, robust, leverage.
5. Check against the checklist
Run the checklist at the end of skill-template.md. In this plugin repo, also run:
bash scripts/validate.sh
Expected: OK: validator passed. Outside the repo, run the checklist's shell snippet, which reproduces the three checks (frontmatter, description rule, links).
6. Verify the skill triggers
Describe a realistic task in one sentence and check that the description would match it and not match an unrelated one. Rewrite the description if not. Then run the skill's own audit step on a real repo and confirm it changes nothing on a second run.
7. Report
Print: path written, the verified versions with sources, what is unverified, and (for upstream) the registration steps left for the maintainer: README list, CHANGELOG entry, manifest listing. Do not edit those yourself unless asked.