Skill Builder

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

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:

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

1. Discover existing conventions (look at other skills in the repo).
2. Draft a micro-spec (goal/non-goals, routing, tool boundaries).
3. Create /<skill-name>/SKILL.md with:
   • front matter (name/description + triggers)
   • router table
   • safety rules
   • minimal workflows (or links to references/)
4. Create /<skill-name>/README.md with install + entry points.
5. Validate (see Validation).
6. 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

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

Phase 4: DELETE Flow

1. Confirm skill folder.
2. Identify dependents (root README.md, other skill references).
3. Remove skill and update references.
4. 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:

1. Add one new router row.
2. Add the minimal new procedure.
3. If it grows: split into references/<topic>.md.
4. Add/adjust examples.
5. 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:

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

---
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:

1. Frontmatter
2. Router table
3. Safety rules
4. Short workflows
5. 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.