Skill Builder
Unified, security-first skill builder.
This skill is intentionally opinionated:
- Prefer no new skill if a simpler change works.
- When you do create a skill, make it boring, testable, and hard to misuse.
- Keep one clear router and avoid overlapping descriptions across skills.
- Stay model-agnostic and harness-agnostic unless the target environment explicitly requires otherwise.
Operation Router
| User intent |
Operation |
Output |
| create/build/make/new skill |
CREATE |
new skill folder + SKILL.md + only the companion files actually needed |
| update/modify/improve skill |
UPDATE |
minimal diff, keep scope stable |
| delete/remove skill |
DELETE |
remove skill + update any dependent references |
| add content/route/workflow to skill |
ADD |
new router row + minimal supporting procedure |
| validate skill |
VALIDATE |
evidence-backed validation report + fixes |
| rename skill |
RENAME |
safe rename + reference updates |
Operation Selection Rules
Use the smallest operation that solves the request:
- CREATE — new user-facing capability or clearly distinct intent/description domain.
- UPDATE — improve an existing skill without changing its core scope.
- ADD — add one new route, example, or sub-workflow inside the current scope.
- RENAME — change identity/path/name while preserving mostly the same behavior.
- DELETE — remove obsolete capability because it is superseded, merged, or no longer useful.
- VALIDATE — inspect correctness without broadening scope.
If uncertain, default to UPDATE rather than CREATE.
What "Correct" Means
This skill treats "correct" as:
- Conforms to the Agent Skills spec where the spec is explicit.
- Uses progressive disclosure: concise
SKILL.md, deeper docs only when needed.
- Has unambiguous activation: specific description + non-overlapping neighboring skills.
- Is safe: no secrets, no default-destructive commands, explicit confirmation boundaries.
- Produces validation evidence instead of relying on vibes.
Phase 0: First-Principles Check (Mandatory)
Run this before any CREATE or UPDATE:
- QUESTION: what problem, for who, measured how?
- DELETE: can an existing skill, README section, script, or template solve it?
- SIMPLIFY: what is the smallest change that works?
- ACCELERATE: only after (2) and (3)
- AUTOMATE: create a new skill only if it will be reused
If the answer is "no skill", propose:
- a README section
- a small script
- a usage snippet users can copy
- a targeted update to an existing skill
Phase 1: Detect Target + Name
Required by the Agent Skills spec
- Skill directory contains
SKILL.md.
SKILL.md starts with valid YAML frontmatter.
name matches the parent directory name.
description explains what the skill does and when to use it.
Recommended by this skill
- Keep
SKILL.md focused on router + core rules.
- Add
references/, scripts/, assets/, or README.md only when they add real value.
- Keep references one level deep from
SKILL.md.
- Put nonstandard metadata under
metadata instead of inventing new top-level fields.
Naming
- Use kebab-case (
my-skill-name).
- Avoid generic names (
tools, helper).
- Prefer names that describe a distinct job to be done.
Description design
The description field is the primary discovery surface.
Write it to cover:
- what the skill does
- when to use it
- likely user wording, domain terms, and near-synonyms
Do not depend on a custom top-level triggers field for portability. If you want trigger examples, keep them in the body, metadata, or eval fixtures.
Confirmation Boundary
Safe without confirmation:
- read-only inspection
- drafting content
- local validation
- proposing diffs
Require confirmation before:
- deleting files or folders
- renaming skill folders
- overwriting user-authored content
- changing trigger semantics in ways that may alter discovery behavior
- editing repo indexes or catalogs
- installing dependencies or using networked side effects
Phase 2: CREATE Flow
Inputs (minimum)
- Name
- Goal + non-goals
- Description draft that covers what + when
- Optional capability constraints if the target client supports them
CREATE Steps
- Discover existing conventions in the target repo.
- Draft a micro-spec: goal, non-goals, router, safety boundary.
- Create
/<skill-name>/SKILL.md with:
- frontmatter (
name, description, optional spec-supported fields)
- router table
- safety and confirmation rules
- short workflows or links to
references/
- Add companion files only if justified:
README.md for human-facing install/overview
references/ for deep workflows
scripts/ for executable helpers
assets/ for templates/resources
- Validate using the evidence rules below.
- If the repo maintains an index, update it.
Output Contract (CREATE)
Always return:
- files created/edited
- description added or changed
- whether optional fields like
compatibility, metadata, or allowed-tools were used
- one minimal smoke-test prompt
- validation report: pass/fail + evidence + remaining risks
Phase 3: UPDATE Flow
- Read the current skill.
- Identify the actual user goal.
- Apply the smallest diff that solves it.
- Re-run validation.
- Keep scope and description stable unless a broader change is explicitly requested.
Output Contract (UPDATE)
Return:
- files changed
- behavior changed
- description change: yes/no
- validation report
- risks or follow-ups
Phase 4: DELETE Flow
- Confirm the target skill folder.
- Identify dependents: indexes, references, sibling skills.
- Remove the skill and update references.
- Provide rollback instructions.
Output Contract (DELETE)
Return:
- removed paths
- references updated
- rollback note
- validation/report of any remaining broken links
Phase 5: ADD Content to a Skill
Rules for skill growth:
- Never duplicate description intent across multiple skills in the same install.
- Route by intent first, then load deeper sections.
- Keep
SKILL.md readable: short tables, stable templates, deep detail in references/.
Add steps:
- Add one new router row or one tightly scoped section.
- Add the minimal new procedure.
- If it grows, split into
references/<topic>.md.
- Add or update examples.
- Re-check neighboring skills for overlap.
Phase 6: RENAME Flow
- Confirm old and new names.
- Rename the folder and update frontmatter
name.
- Update internal and repo-level references.
- Validate links, name/path parity, and discovery wording.
Output Contract (RENAME)
Return:
- old name → new name
- moved paths
- references updated
- validation report
Validation
Validation Requirements
A skill is not validated until you produce evidence for all three layers:
- Spec validation — structure and YAML correctness
- Trigger validation — the description should trigger when it should, and not trigger on near-misses
- Output validation — the skill improves or constrains the resulting work on realistic tasks
Skill Validation Checklist
- Frontmatter includes valid
name and description.
- Frontmatter is valid YAML, not just visually plausible Markdown metadata.
name matches the parent directory.
- Description clearly states what + when.
- Any extra frontmatter stays within spec-supported fields unless the target environment explicitly supports more.
- Router is present.
- Confirmation boundary is explicit.
- No secrets; no private paths unless the target repo is intentionally private.
- No unscoped destructive instructions.
- Progressive disclosure is respected.
- Trigger hygiene has been checked against neighboring skills.
Spec Validation (Recommended)
If available:
skills-ref validate ./<skill-name>
If not available, validate manually using the rules in references/validation.md.
Capability Safety
- Prefer the least-privileged capability that can complete the task.
- Inspect/search before executing commands.
- If command execution is needed, scope it tightly.
- Never recommend
rm -rf, git reset --hard, or push --force as defaults.
Templates
Skill Frontmatter
---
name: my-skill
description: Use this skill when you need to do X, Y, or Z. It handles A and B and is relevant when the user asks for C.
compatibility: Optional. Mention required runtimes, system tools, or environment assumptions.
metadata:
version: "0.1"
allowed-tools: Optional experimental field. Only include it when the target client supports it and the skill benefits from a constrained tool list.
---
Minimum Viable Portable Skill
- Frontmatter
- One-paragraph purpose/activation guidance
- Router table
- Safety + confirmation rules
- Short workflows
- Optional
references/ only when needed
References
references/checklist.md (authoring checklist)
references/templates.md (copy/paste templates)
references/validation.md (spec, trigger, and output validation)
What This Skill Is For (Practical Examples)
- "Create a skill that scaffolds new skills" → CREATE.
- "Make this skill more portable across agent products" → UPDATE.
- "Rename this skill without breaking references" → RENAME.
- "Check whether this skill will trigger reliably" → VALIDATE.
- "Make skills consistent across repos" → UPDATE or ADD, depending on scope.
1---2name: skill-builder3description: |4 Build correct, consistent Agent Skills for any compatible agent product. Use when creating,5 updating, renaming, deleting, or validating a skill, or when improving skill descriptions,6 structure, safety rules, progressive disclosure, or trigger reliability.7license: MIT8compatibility: "Agent Skills spec (agentskills.io). Works with any agent product that supports SKILL.md frontmatter + Markdown."9metadata:10 source: https://skillmd.com/skills/bntvllnt/skill-builder11 version: "1.1"12---1314# Skill Builder1516Unified, security-first skill builder.1718This skill is intentionally opinionated:19- Prefer no new skill if a simpler change works.20- When you do create a skill, make it boring, testable, and hard to misuse.21- Keep one clear router and avoid overlapping descriptions across skills.22- Stay model-agnostic and harness-agnostic unless the target environment explicitly requires otherwise.2324## Operation Router2526| User intent | Operation | Output |27|---|---|---|28| create/build/make/new skill | CREATE | new skill folder + `SKILL.md` + only the companion files actually needed |29| update/modify/improve skill | UPDATE | minimal diff, keep scope stable |30| delete/remove skill | DELETE | remove skill + update any dependent references |31| add content/route/workflow to skill | ADD | new router row + minimal supporting procedure |32| validate skill | VALIDATE | evidence-backed validation report + fixes |33| rename skill | RENAME | safe rename + reference updates |3435## Operation Selection Rules3637Use the smallest operation that solves the request:3839- **CREATE** — new user-facing capability or clearly distinct intent/description domain.40- **UPDATE** — improve an existing skill without changing its core scope.41- **ADD** — add one new route, example, or sub-workflow inside the current scope.42- **RENAME** — change identity/path/name while preserving mostly the same behavior.43- **DELETE** — remove obsolete capability because it is superseded, merged, or no longer useful.44- **VALIDATE** — inspect correctness without broadening scope.4546If uncertain, default to **UPDATE** rather than CREATE.4748## What "Correct" Means4950This skill treats "correct" as:5152- Conforms to the Agent Skills spec where the spec is explicit.53- Uses progressive disclosure: concise `SKILL.md`, deeper docs only when needed.54- Has unambiguous activation: specific description + non-overlapping neighboring skills.55- Is safe: no secrets, no default-destructive commands, explicit confirmation boundaries.56- Produces validation evidence instead of relying on vibes.5758## Phase 0: First-Principles Check (Mandatory)5960Run this before any CREATE or UPDATE:61621. QUESTION: what problem, for who, measured how?632. DELETE: can an existing skill, README section, script, or template solve it?643. SIMPLIFY: what is the smallest change that works?654. ACCELERATE: only after (2) and (3)665. AUTOMATE: create a new skill only if it will be reused6768If the answer is "no skill", propose:69- a README section70- a small script71- a usage snippet users can copy72- a targeted update to an existing skill7374## Phase 1: Detect Target + Name7576### Required by the Agent Skills spec7778- Skill directory contains `SKILL.md`.79- `SKILL.md` starts with valid YAML frontmatter.80- `name` matches the parent directory name.81- `description` explains what the skill does and when to use it.8283### Recommended by this skill8485- Keep `SKILL.md` focused on router + core rules.86- Add `references/`, `scripts/`, `assets/`, or `README.md` only when they add real value.87- Keep references one level deep from `SKILL.md`.88- Put nonstandard metadata under `metadata` instead of inventing new top-level fields.8990### Naming9192- Use kebab-case (`my-skill-name`).93- Avoid generic names (`tools`, `helper`).94- Prefer names that describe a distinct job to be done.9596### Description design9798The `description` field is the primary discovery surface.99100Write it to cover:101- **what** the skill does102- **when** to use it103- likely user wording, domain terms, and near-synonyms104105Do not depend on a custom top-level `triggers` field for portability. If you want trigger examples, keep them in the body, `metadata`, or eval fixtures.106107## Confirmation Boundary108109Safe without confirmation:110- read-only inspection111- drafting content112- local validation113- proposing diffs114115Require confirmation before:116- deleting files or folders117- renaming skill folders118- overwriting user-authored content119- changing trigger semantics in ways that may alter discovery behavior120- editing repo indexes or catalogs121- installing dependencies or using networked side effects122123## Phase 2: CREATE Flow124125### Inputs (minimum)126127- Name128- Goal + non-goals129- Description draft that covers what + when130- Optional capability constraints if the target client supports them131132### CREATE Steps1331341. Discover existing conventions in the target repo.1352. Draft a micro-spec: goal, non-goals, router, safety boundary.1363. Create `/<skill-name>/SKILL.md` with:137 - frontmatter (`name`, `description`, optional spec-supported fields)138 - router table139 - safety and confirmation rules140 - short workflows or links to `references/`1414. Add companion files only if justified:142 - `README.md` for human-facing install/overview143 - `references/` for deep workflows144 - `scripts/` for executable helpers145 - `assets/` for templates/resources1465. Validate using the evidence rules below.1476. If the repo maintains an index, update it.148149### Output Contract (CREATE)150151Always return:152- files created/edited153- description added or changed154- whether optional fields like `compatibility`, `metadata`, or `allowed-tools` were used155- one minimal smoke-test prompt156- validation report: pass/fail + evidence + remaining risks157158## Phase 3: UPDATE Flow1591601. Read the current skill.1612. Identify the actual user goal.1623. Apply the smallest diff that solves it.1634. Re-run validation.1645. Keep scope and description stable unless a broader change is explicitly requested.165166### Output Contract (UPDATE)167168Return:169- files changed170- behavior changed171- description change: yes/no172- validation report173- risks or follow-ups174175## Phase 4: DELETE Flow1761771. Confirm the target skill folder.1782. Identify dependents: indexes, references, sibling skills.1793. Remove the skill and update references.1804. Provide rollback instructions.181182### Output Contract (DELETE)183184Return:185- removed paths186- references updated187- rollback note188- validation/report of any remaining broken links189190## Phase 5: ADD Content to a Skill191192Rules for skill growth:193- Never duplicate description intent across multiple skills in the same install.194- Route by intent first, then load deeper sections.195- Keep `SKILL.md` readable: short tables, stable templates, deep detail in `references/`.196197Add steps:1981. Add one new router row or one tightly scoped section.1992. Add the minimal new procedure.2003. If it grows, split into `references/<topic>.md`.2014. Add or update examples.2025. Re-check neighboring skills for overlap.203204## Phase 6: RENAME Flow2052061. Confirm old and new names.2072. Rename the folder and update frontmatter `name`.2083. Update internal and repo-level references.2094. Validate links, name/path parity, and discovery wording.210211### Output Contract (RENAME)212213Return:214- old name → new name215- moved paths216- references updated217- validation report218219## Validation220221### Validation Requirements222223A skill is not validated until you produce evidence for all three layers:2242251. **Spec validation** — structure and YAML correctness2262. **Trigger validation** — the description should trigger when it should, and not trigger on near-misses2273. **Output validation** — the skill improves or constrains the resulting work on realistic tasks228229### Skill Validation Checklist230231- Frontmatter includes valid `name` and `description`.232- Frontmatter is valid YAML, not just visually plausible Markdown metadata.233- `name` matches the parent directory.234- Description clearly states what + when.235- Any extra frontmatter stays within spec-supported fields unless the target environment explicitly supports more.236- Router is present.237- Confirmation boundary is explicit.238- No secrets; no private paths unless the target repo is intentionally private.239- No unscoped destructive instructions.240- Progressive disclosure is respected.241- Trigger hygiene has been checked against neighboring skills.242243### Spec Validation (Recommended)244245If available:246247```bash248skills-ref validate ./<skill-name>249```250251If not available, validate manually using the rules in `references/validation.md`.252253### Capability Safety254255- Prefer the least-privileged capability that can complete the task.256- Inspect/search before executing commands.257- If command execution is needed, scope it tightly.258- Never recommend `rm -rf`, `git reset --hard`, or `push --force` as defaults.259260## Templates261262### Skill Frontmatter263264```yaml265---266name: my-skill267description: Use this skill when you need to do X, Y, or Z. It handles A and B and is relevant when the user asks for C.268compatibility: Optional. Mention required runtimes, system tools, or environment assumptions.269metadata:270 version: "0.1"271allowed-tools: Optional experimental field. Only include it when the target client supports it and the skill benefits from a constrained tool list.272---273```274275### Minimum Viable Portable Skill2762771. Frontmatter2782. One-paragraph purpose/activation guidance2793. Router table2804. Safety + confirmation rules2815. Short workflows2826. Optional `references/` only when needed283284## References285286- `references/checklist.md` (authoring checklist)287- `references/templates.md` (copy/paste templates)288- `references/validation.md` (spec, trigger, and output validation)289290## What This Skill Is For (Practical Examples)291292- "Create a skill that scaffolds new skills" → CREATE.293- "Make this skill more portable across agent products" → UPDATE.294- "Rename this skill without breaking references" → RENAME.295- "Check whether this skill will trigger reliably" → VALIDATE.296- "Make skills consistent across repos" → UPDATE or ADD, depending on scope.