Custom Skill Builder
Purpose
Create focused, portable skills that load at the right time and give an agent information it would not reliably infer on its own.
Skill brief
- Read
references/skill-authoring-contract.md.
- Clarify the skill intent in one sentence: what recurring job should this skill make easier?
- Decide whether this is a new skill, an update, or a project-local skill.
- Check for overlap with existing skills. Extend an existing skill when the new behavior is a narrow variant; create a new skill when it has a distinct trigger, workflow, or ownership boundary.
- If the skill depends on current libraries, APIs, CLIs, MCP servers, or platform behavior, verify those docs with Context7 MCP before writing procedural guidance.
Authoring method
- Write a lowercase hyphenated
name and a description that says what the skill does and when it should activate.
- Keep the body focused on the recurring decision or procedure. Put conditional detail in directly linked references.
- Add
scripts/ only for deterministic repeated work and assets/ only for files used in output.
- Add client metadata such as
agents/openai.yaml only when it improves a supported client; the core skill must remain usable without it.
- Register the skill in routing only when it participates in a multi-skill workflow.
- Validate against the Agent Skills specification and this repository's routing rules.
- Forward-test realistic prompts that should and should not activate the skill. Compare the result with the previous version or a no-skill baseline when the behavior is important.
Portability rules
- Preserve the user's chosen product, scope, and authorization boundary.
- Use current primary documentation for external technology behavior.
- Do not copy manuals into a skill. Keep only the decisions and procedures the agent needs.
- Do not require one fixed heading template. Structure the body around the actual task.
- Do not add a skill-level README, changelog, or installation guide unless it is part of the requested package.
Skill package
- New or updated skill folder
- Valid
SKILL.md
- Supporting resources that have a concrete use
- Routing and client metadata where applicable
- Validation and forward-test evidence
Ready when
- The name matches the folder and Agent Skills naming rules.
- The description is discriminating without becoming a capability catalogue.
- The body contains no generic advice the target model already knows.
- References are discoverable and resources are portable.
- Tests show both useful activation and non-activation.
- No machine-specific paths, placeholders, or hidden permissions remain.
Handoff
Report the skill name, activation boundary, resources, routing impact, validation result, and one realistic invocation. Use self-improvement-loop only when the change responds to measured agent failure.
References
references/skill-authoring-contract.md: compact rules for skill scope, anatomy, progressive disclosure, metadata, validation, and forward testing.
1---2name: custom-skill-builder3description: Create or update a reusable Agent Skill in the open SKILL.md format. Use for project, team, domain, or tool workflows that need a precise trigger and repeatable procedure. Add references, scripts, assets, client metadata, or routing only when the skill needs them; do not create a new skill for a one-off instruction or a narrow variant already owned elsewhere.4---56# Custom Skill Builder78## Purpose910Create focused, portable skills that load at the right time and give an agent information it would not reliably infer on its own.1112## Skill brief13141. Read `references/skill-authoring-contract.md`.152. Clarify the skill intent in one sentence: what recurring job should this skill make easier?163. Decide whether this is a new skill, an update, or a project-local skill.174. Check for overlap with existing skills. Extend an existing skill when the new behavior is a narrow variant; create a new skill when it has a distinct trigger, workflow, or ownership boundary.185. If the skill depends on current libraries, APIs, CLIs, MCP servers, or platform behavior, verify those docs with Context7 MCP before writing procedural guidance.1920## Authoring method21221. Write a lowercase hyphenated `name` and a `description` that says what the skill does and when it should activate.232. Keep the body focused on the recurring decision or procedure. Put conditional detail in directly linked references.243. Add `scripts/` only for deterministic repeated work and `assets/` only for files used in output.254. Add client metadata such as `agents/openai.yaml` only when it improves a supported client; the core skill must remain usable without it.265. Register the skill in routing only when it participates in a multi-skill workflow.276. Validate against the Agent Skills specification and this repository's routing rules.287. Forward-test realistic prompts that should and should not activate the skill. Compare the result with the previous version or a no-skill baseline when the behavior is important.2930## Portability rules3132- Preserve the user's chosen product, scope, and authorization boundary.33- Use current primary documentation for external technology behavior.34- Do not copy manuals into a skill. Keep only the decisions and procedures the agent needs.35- Do not require one fixed heading template. Structure the body around the actual task.36- Do not add a skill-level README, changelog, or installation guide unless it is part of the requested package.3738## Skill package3940- New or updated skill folder41- Valid `SKILL.md`42- Supporting resources that have a concrete use43- Routing and client metadata where applicable44- Validation and forward-test evidence4546## Ready when4748- The name matches the folder and Agent Skills naming rules.49- The description is discriminating without becoming a capability catalogue.50- The body contains no generic advice the target model already knows.51- References are discoverable and resources are portable.52- Tests show both useful activation and non-activation.53- No machine-specific paths, placeholders, or hidden permissions remain.5455## Handoff5657Report the skill name, activation boundary, resources, routing impact, validation result, and one realistic invocation. Use `self-improvement-loop` only when the change responds to measured agent failure.5859## References6061- `references/skill-authoring-contract.md`: compact rules for skill scope, anatomy, progressive disclosure, metadata, validation, and forward testing.
ashermahonin