Skill Builder

Unified, security-first skill builder.

This skill is intentionally opinionated:

Prefer no new skill if a simpler change works (project docs, a script, or a small snippet).
When you do create a skill, make it boring, testable, and hard to misuse.
Keep one clear router and avoid overlapping triggers across skills.

Operation Router

User intent	Operation	Output
create/build/make/new skill	CREATE	new skill folder + `SKILL.md` + `README.md`
update/modify/improve skill	UPDATE	minimal diff, keep triggers stable
delete/remove skill	DELETE	remove skill + update repo index
add content/route/workflow to skill	ADD	new router row + new section file (when needed)
validate skill	VALIDATE	checklist results + fixes
rename skill	RENAME	safe rename + reference updates

What "Correct" Means

This skill treats "correct" as:

Conforms to the Agent Skills spec (directory +
```
SKILL.md
```
frontmatter constraints).
Uses progressive disclosure: small
```
SKILL.md
```
, deeper docs in
```
references/
```
.
Has unambiguous activation: specific description + non-overlapping triggers.
Is safe: no secrets, no default-destructive commands, tool usage is scoped.

Phase 0: First-Principles Check (Mandatory)

Run this before ANY CREATE/UPDATE:

QUESTION: what problem, for who, measured how?
DELETE: can an existing component/skill/command solve it?
SIMPLIFY: smallest change that works (often a project instruction file)
ACCELERATE: only after (2) and (3)
AUTOMATE: create a component 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

Phase 1: Detect Target + Name

Target repository layout

This repo layout:

```
/<skill-name>/SKILL.md
```
(home/router)
```
/<skill-name>/README.md
```
(short overview)
optional:
```
/<skill-name>/references/*.md
```
(split workflows)

Spec Rules (Agent Skills)

From the Agent Skills specification:

Skill folder name must match
```
name
```
.
```
name
```
constraints: 1-64 chars; lowercase letters/numbers/hyphens; no leading/trailing
```
-
```
; no
```
--
```
.
```
description
```
should say what + when; max 1024 chars.
Optional frontmatter fields you may include:
```
license
```
,
```
compatibility
```
,
```
metadata
```
,
```
allowed-tools
```
.

Reference: https://agentskills.io/specification

Naming

Use kebab-case (
```
my-skill-name
```
).
Avoid generic names (
```
tools
```
,
```
helper
```
).
Prefer verbs for commands (
```
review-pr
```
,
```
sync-main
```
).

Phase 2: CREATE Flow

Inputs (minimum)

Name
Goal + non-goals
Triggers (what user says)
Allowed tools (tightest possible)

CREATE Steps

Discover existing conventions (look at other skills in the repo).
Draft a micro-spec (goal/non-goals, routing, tool boundaries).
Create
```
/<skill-name>/SKILL.md
```
with:
- front matter (name/description + triggers)
- router table
- safety rules
- minimal workflows (or links to
```
references/
```
  )
Create
```
/<skill-name>/README.md
```
with install + entry points.
Validate (see Validation).
If the repo has an index of skills (commonly a
```
README.md
```
), add/update the entry.

Output Contract (CREATE)

When creating a skill, always return:

Files created/edited (paths only)
Trigger phrases added
One minimal "smoke test" prompt (how to activate it)
Validation result (pass/fail + what to fix)

Phase 3: UPDATE Flow

Read current skill.
Identify actual user goal (avoid refactors).
Apply minimal diff.
Re-run validation checklist.
Keep triggers stable unless explicitly requested.

Phase 4: DELETE Flow

Confirm skill folder.
Identify dependents (root
```
README.md
```
, other skill references).
Remove skill and update references.
Provide rollback note (restore from git).

Phase 5: ADD Content to a Skill

Rules for skill growth:

Never duplicate trigger phrases across multiple skills in the same install.
Route by intent first, then load deeper sections.
Keep SKILL.md readable: prefer short tables + stable templates.

Add steps:

Add one new router row.
Add the minimal new procedure.
If it grows: split into
```
references/<topic>.md
```
.
Add/adjust examples.
Re-check cross-skill consistency.

Validation

Skill Validation Checklist

Front matter includes
```
name
```
and
```
description
```
.
Has a router (how to decide what to do).
Defines what is safe to run without confirmation vs requires confirmation.
No secrets; no links to private paths.
No unscoped destructive instructions.
Trigger hygiene: no overlapping triggers with existing skills in the repo.
Docs split: if SKILL.md becomes long, move workflows into
```
references/
```
.

Spec Validation (Recommended)

If you have the reference validator available (optional), run:

bash

skills-ref validate ./<skill-name>

If not available, validate manually using the rules in "Spec Rules" above.

Tool Safety

Prefer Read/Glob/Grep before Bash.
If Bash is needed, scope it (git-only, or specific commands).
Never recommend
```
rm -rf
```
,
```
git reset --hard
```
,
```
push --force
```
as defaults.

Templates

Skill Front Matter

yaml

---
name: my-skill
description: Describe what the skill does and when to use it. Include trigger phrases.
compatibility: Optional. Mention required system tools, network needs, or target environments.
metadata:
  version: "0.1"
allowed-tools: Optional. Space-delimited list. Prefer the narrowest set possible.
---

Progressive Disclosure Pattern

Keep

SKILL.md

as:

Frontmatter
Router table
Safety rules
Short workflows
Links to
```
references/*.md
```
for deep details

References

```
references/checklist.md
```
(authoring checklist)
```
references/templates.md
```
(copy/paste templates)
```
references/validation.md
```
(validation flow + trigger hygiene)

What This Skill Is For (Practical Examples)

"Create a skill that scaffolds new skills" → create a skill + templates + validation.
"Update my git workflow" → improve the router + split workflows into
```
references/
```
.
"Make skills consistent across repos" → enforce naming/triggers/tool boundaries.

skill-builder

NPX Install

Tags

SKILL.md Content