Writing Skills
Create or reshape a skill so it triggers at the right time, stays lean, and
matches this repo's source and build rules.
Read first
AGENTS.md section ## Writing Agent/Skill Instructions for markdown signal rules.
references/skill-principles.md for invocation, description, disclosure, split,
and pruning rules.
references/repo-conventions.md for src/skills/, plugin manifests, overlays,
generated outputs, and verification.
src/skills/reviewing-instructions/references/scoring-rubric.md only after the
draft exists and quality needs a final check.
Use this skill for
- creating a new skill
- rewriting a skill body or description
- splitting one skill into a skill plus references
- splitting one skill into two skills when the trigger or workflow boundary is real
- merging or extending overlapping skills after checking the neighboring skills
- pruning bloated skill prose, duplicate rules, or weak trigger phrasing
- adding target overlays or support files to a skill
Do not use this skill for
- scoring or linting prompt files without editing them; use
reviewing-instructions
- broad agent, hook, extension, MCP, or package audits outside skill authoring;
use
evolving-config
- ordinary docs, READMEs, or code comments; use
documenting-code
- external library or API lookup; use
looking-up-docs
- broad design debate before a concrete skill change exists; use
brainstorming-ideas
Workflow
- Find the source of truth under
src/skills/<name>/. Read the owning
src/.agentbundler/packages/*.json and the closest neighboring skills before
editing. Treat dist/ as generated.
- State the smallest correct shape:
- edit the current skill
- move conditional detail to
references/
- add a
.agentbundler/targets/<target>.json overlay
- split into two skills
- merge or fold into a neighboring skill
- Decide invocation mode and trigger surface.
- Model-invoked: use when the agent or another skill must discover it on its
own.
- User-invoked: use when it is mostly a manual expert tool or reference.
- Keep one trigger per branch. Name real neighboring skills when overlap is
possible. Put the NOT-clause in the description, not as an afterthought.
- Split content per the information hierarchy in
references/skill-principles.md. Keep only common-path rules in the main
body. Move conditional detail to references/. Use Agent Bundler JSON
overlays only when the base cannot stay vendor-neutral: frontmatterPatch,
bodyPatch, files, and deletedFiles.
- Tighten wording until each line changes behavior. Delete generic agent advice,
duplicated rules, and pretty prose.
- When adding or removing a public skill, update the owning package JSON in
src/.agentbundler/packages/. Update AGENTS.md and README.md when they
expose the public skill surface or counts.
- Before claiming done, run the narrowest verification that proves the new skill
compiles and reads well.
- If quality is still uncertain, run
reviewing-instructions on the new or
changed skill and apply the highest-value fixes.
Writing rules
- Bias toward predictability over style.
- Prefer headers, bullets, numbered steps, and short imperative lines.
- Keep each meaning in one place.
- Inline only what every trigger path needs.
- Use references for detail that only some branches need.
- Add an output contract when the skill produces findings, plans, edits, or
artifacts.
- Add failure handling for ambiguous scope, missing inputs, generated files,
unavailable tools, and verification gaps.
- Do not create a new skill just to rename an existing trigger.
- Do not add a target overlay when a vendor-neutral base already works.
Output
Write-capable role:
## Skill Update
Updated:
- `path` — <created or changed>
Plugin:
- <plugin name or unchanged>
Routing:
- Invocation: model-invoked | user-invoked
- Trigger surface: <main trigger terms>
- Excludes: <neighbor skills or none>
Verified:
- <check>: passed | skipped (<reason>)
Follow-up:
- <reviewing-instructions run, docs update, or none>
Read-only role:
## Proposed Skill Change
Files:
- `path`
Why:
- <routing, disclosure, or repo-convention reason>
Proposed shape:
- Invocation: model-invoked | user-invoked
- Plugin: <plugin>
- References or overlays: <list or none>
Patch summary:
- <small bullet list of edits>
Verification:
- <checks the applier should run, or not run — read-only role>
Failure handling
- Ambiguous request between new skill and neighbor-skill edit: ask one scoped
question before editing.
- Existing skill already covers the job: prefer tightening or extending it over
adding a duplicate.
- Plugin ownership is unclear: list the plausible plugins and ask which public
surface the user wants.
- Generated files differ from source: edit
src/ first, then regenerate.
- Build or compile check is unavailable: report the exact gap and do not claim
generated outputs are current.
- A target needs unique behavior everywhere: add an overlay only after the
vendor-neutral base fails.
1---2description:3 Create, split, slim, or rewrite repository skills. Use when adding a4 new `src/skills/<name>/` skill, editing a skill description, frontmatter, references,5 overlays, or plugin placement, or tightening routing between neighboring skills.6 NOT for score-only instruction review; use reviewing-instructions. NOT for broad7 agent/package config audits; use evolving-config. NOT for ordinary docs; use documenting-code.8name: writing-skills9metadata:10 source: https://skillmd.com/skills/alexei-led/writing-skills11---1213# Writing Skills1415Create or reshape a skill so it triggers at the right time, stays lean, and16matches this repo's source and build rules.1718## Read first1920- `AGENTS.md` section `## Writing Agent/Skill Instructions` for markdown signal rules.21- `references/skill-principles.md` for invocation, description, disclosure, split,22 and pruning rules.23- `references/repo-conventions.md` for `src/skills/`, plugin manifests, overlays,24 generated outputs, and verification.25- `src/skills/reviewing-instructions/references/scoring-rubric.md` only after the26 draft exists and quality needs a final check.2728## Use this skill for2930- creating a new skill31- rewriting a skill body or description32- splitting one skill into a skill plus references33- splitting one skill into two skills when the trigger or workflow boundary is real34- merging or extending overlapping skills after checking the neighboring skills35- pruning bloated skill prose, duplicate rules, or weak trigger phrasing36- adding target overlays or support files to a skill3738## Do not use this skill for3940- scoring or linting prompt files without editing them; use `reviewing-instructions`41- broad agent, hook, extension, MCP, or package audits outside skill authoring;42 use `evolving-config`43- ordinary docs, READMEs, or code comments; use `documenting-code`44- external library or API lookup; use `looking-up-docs`45- broad design debate before a concrete skill change exists; use46 `brainstorming-ideas`4748## Workflow49501. Find the source of truth under `src/skills/<name>/`. Read the owning51 `src/.agentbundler/packages/*.json` and the closest neighboring skills before52 editing. Treat `dist/` as generated.532. State the smallest correct shape:54 - edit the current skill55 - move conditional detail to `references/`56 - add a `.agentbundler/targets/<target>.json` overlay57 - split into two skills58 - merge or fold into a neighboring skill593. Decide invocation mode and trigger surface.60 - Model-invoked: use when the agent or another skill must discover it on its61 own.62 - User-invoked: use when it is mostly a manual expert tool or reference.63 - Keep one trigger per branch. Name real neighboring skills when overlap is64 possible. Put the NOT-clause in the description, not as an afterthought.654. Split content per the information hierarchy in66 `references/skill-principles.md`. Keep only common-path rules in the main67 body. Move conditional detail to `references/`. Use Agent Bundler JSON68 overlays only when the base cannot stay vendor-neutral: `frontmatterPatch`,69 `bodyPatch`, `files`, and `deletedFiles`.705. Tighten wording until each line changes behavior. Delete generic agent advice,71 duplicated rules, and pretty prose.726. When adding or removing a public skill, update the owning package JSON in73 `src/.agentbundler/packages/`. Update `AGENTS.md` and `README.md` when they74 expose the public skill surface or counts.757. Before claiming done, run the narrowest verification that proves the new skill76 compiles and reads well.778. If quality is still uncertain, run `reviewing-instructions` on the new or78 changed skill and apply the highest-value fixes.7980## Writing rules8182- Bias toward predictability over style.83- Prefer headers, bullets, numbered steps, and short imperative lines.84- Keep each meaning in one place.85- Inline only what every trigger path needs.86- Use references for detail that only some branches need.87- Add an output contract when the skill produces findings, plans, edits, or88 artifacts.89- Add failure handling for ambiguous scope, missing inputs, generated files,90 unavailable tools, and verification gaps.91- Do not create a new skill just to rename an existing trigger.92- Do not add a target overlay when a vendor-neutral base already works.9394## Output9596Write-capable role:9798```markdown99## Skill Update100101Updated:102103- `path` — <created or changed>104105Plugin:106107- <plugin name or unchanged>108109Routing:110111- Invocation: model-invoked | user-invoked112- Trigger surface: <main trigger terms>113- Excludes: <neighbor skills or none>114115Verified:116117- <check>: passed | skipped (<reason>)118119Follow-up:120121- <reviewing-instructions run, docs update, or none>122```123124Read-only role:125126```markdown127## Proposed Skill Change128129Files:130131- `path`132133Why:134135- <routing, disclosure, or repo-convention reason>136137Proposed shape:138139- Invocation: model-invoked | user-invoked140- Plugin: <plugin>141- References or overlays: <list or none>142143Patch summary:144145- <small bullet list of edits>146147Verification:148149- <checks the applier should run, or not run — read-only role>150```151152## Failure handling153154- Ambiguous request between new skill and neighbor-skill edit: ask one scoped155 question before editing.156- Existing skill already covers the job: prefer tightening or extending it over157 adding a duplicate.158- Plugin ownership is unclear: list the plausible plugins and ask which public159 surface the user wants.160- Generated files differ from source: edit `src/` first, then regenerate.161- Build or compile check is unavailable: report the exact gap and do not claim162 generated outputs are current.163- A target needs unique behavior everywhere: add an overlay only after the164 vendor-neutral base fails.