Skill Builder

Use this skill when the job is to decide, build, or audit a skill itself.

This is a narrow builder, not a meta-agent and not a skill factory. Prefer the

smallest useful answer.

Modes

1. Decide — choose between plain edit, existing tool/skill, subagent, or a lean skill
2. Build — draft a minimal skill skeleton only when a skill is justified
3. Audit — tighten or lightly restructure an existing skill

Use when

• deciding whether a new skill is justified at all
• drafting a lean new skill skeleton after deciding a skill is warranted
• tightening an existing skill's trigger description or scope
• moving detail out of SKILL.md into references/
• auditing a skill for bloat, stale instructions, duplicate content, or spec drift

Do not use when

• a plain file edit will solve the problem faster
• an existing tool or installed skill already covers the work
• the problem is implementation labor across many files rather than reusable guidance
• you are inventing process theater to justify a skill
• you are trying to generate a large framework of boilerplate, governance, or publishing machinery

Default workflow

1. Run the decision tree first

Read references/decision-tree.md and choose between plain edit, existing

tool/skill, subagent, or a lean skill.

1. If the answer is not "use a skill," stop there

Prefer the honest recommendation over unnecessary skill creation.

1. If a skill is justified, build the smallest workable skeleton

Read references/supporting-files-guide.md and produce only what is earned:

• skill folder
• SKILL.md
• references/ with 1-3 files only if they reduce context load or hold optional detail
• assets/ only if the skill produces output that depends on bundled files
• scripts/ stub only if deterministic execution is clearly warranted

1. Write the skill body well

Read references/writing-patterns.md for guidance on voice, examples,

output templates, and explaining the why behind instructions.

1. Keep SKILL.md minimal

Include only:

• clear frontmatter (name, description) — see references/frontmatter-patterns.md
• scope and non-scope
• default workflow
• reference pointers when optional detail is useful

1. Smoke test before shipping

Try 2-3 realistic prompts against the skill before calling it done:

• one clear trigger (should activate the skill)
• one edge case (should activate but tests a boundary)
• one near-miss (should not activate — tests specificity)

If any of these behave wrong, revisit the description or workflow before shipping.

1. Audit before expanding

Use references/audit-checklist.md to remove bloat, stale claims, weak triggers,

duplicate guidance, and files that do not earn their keep.

1. Apply the Tool Addition Gate lightly

If the proposed skill is compensating for a missing primitive, check this order:

existing tools → lean skill → subagent/retrieval pattern → new tool only if clearly needed.

Build output

When building, produce the smallest useful package in this order:

1. Recommendation

State whether the answer is:

• Use a skill
• Use the existing tool/skill
• Use a subagent
• Do nothing special; just edit it

1. Folder tree

Show a minimal tree such as:

```text

skill-name/

├── SKILL.md

└── references/

└── optional-file.md

```

1. Draft frontmatter

Provide only:

• name
• description

1. SKILL.md outline

Include only the sections the skill actually needs.

1. Optional additions

Suggest 1-3 references/ files if justified.

Suggest an assets/ folder only if the skill needs bundled templates or static files.

Suggest a scripts/ stub only if exact repeatable execution matters.

Optionally suggest publish metadata ideas (description/tags), but do not package or publish.

Minimal build example

Recommendation: Use a skill

skill-name/
├── SKILL.md
└── references/
 └── checklist.md

name: skill-name
description: Helps with X. Use when the user asks for Y or needs Z.

SKILL.md should then contain only:

• scope / non-scope
• default workflow
• pointer to references/checklist.md

Good outcomes

• A plain edit stays a plain edit
• An existing skill gets tightened instead of replaced
• A new skill has a sharp trigger description and a short SKILL.md
• A new skill skeleton is minimal and immediately editable
• Supporting files exist only when they reduce context load or improve reliability
• The skill triggers correctly on natural phrasings (not just its literal name)

Avoid

• turning one-off work into a permanent skill
• adding README, changelog, install notes, or setup clutter inside the skill unless publishing truly needs it
• stuffing examples, schemas, and edge cases into SKILL.md
• creating scripts for things that are better as instructions
• inventing governance layers, registries, dashboards, or lifecycle systems
• writing ALWAYS/NEVER/CRITICAL in all caps instead of explaining reasoning

Works well with

This skill handles the pre-flight phase: deciding if a skill is warranted and

structuring the smallest viable version. For testing, iteration, and benchmarking

of a built skill, hand off to skill-creator (if available), which provides eval

runners, comparison viewers, and description optimization loops.

References

• references/decision-tree.md — choose skill vs tool vs subagent vs plain edit
• references/frontmatter-patterns.md — lean frontmatter, description patterns, and pushy trigger guidance
• references/writing-patterns.md — voice, examples, output templates, and instruction style
• references/supporting-files-guide.md — progressive disclosure model and what belongs in each folder
• references/audit-checklist.md — fast bloat/spec-drift review

Output style

Lead with the recommendation, then provide only the smallest justified build or edit plan.