Build Skill
Create or rewrite one strong, workflow-conformant SKILL.md through targeted failure analysis and review instead of a multi-draft tournament.
Overview
Build Skill is a journey-wide agent skill that authors one high-quality SKILL.md through failure analysis and invariant-driven review—usable whenever a solo builder needs durable agent procedures before relying on ad-hoc
Install
npx skills add https://github.com/camacho/ai-skills --skill build-skillWhat is this skill?
- /build-skill produces a single intentional draft via failure analysis, review, and refinement—not competing drafts
- Writes operational briefs for capable senior engineers: invariants, decision boundaries, evidence, stop rules
- Routes user-level vs project-level scope and exact SKILL.md destination before drafting
- Frontmatter tuned for discovery (when to use) separate from full workflow body
- Token efficiency: rarely needed detail stays out of the main body or loads on demand
Adoption & trust: 572 installs on skills.sh; 1 GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent keeps misfiring because SKILL.md drafts are either vague chat summaries or over-procedural scripts with no clear stop rules and wrong scope.
Who is it for?
Builders maintaining a personal or project skill library who want one disciplined pass after seeing real invocation failures.
Skip if: One-off throwaway prompts, or teams that only need the bundled multi-draft tournament flow from a separate skill-creator stack without custom governance encoding.
When should I use this skill?
Use when creating or rewriting a skill and you want one strong, workflow-conformant version built through failure analysis, review, and refinement instead of a multi-draft tournament.
What do I get? / Deliverables
You ship a single reviewed SKILL.md with discovery-oriented frontmatter, explicit routing, and lean operational briefs your agent can follow without ceremony creep.
- Single reviewed SKILL.md at the routed user- or project-level path
- Discovery-oriented YAML frontmatter with invoke-when description
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Encode a thin validation checklist as a project skill before handing an agent your MVP repo.
Author integrations skill with decision boundaries after a failed run exposed missing stop rules.
Refactor a review skill so frontmatter triggers match when reviewers should invoke it mid-PR.
Turn recurring incident steps into a lean operate skill without shell automaton noise.
How it compares
Single-draft quality loop for SKILL.md authoring—not an MCP server installer and not a generic code generator.
Common Questions / FAQ
Who is build-skill for?
Solo and indie builders (and small teams) who write or curate Claude Code, Cursor, or Codex skills and want one strong SKILL.md without running parallel draft competitions.
When should I use build-skill?
Use it journey-wide whenever you create or rewrite a skill—during Build agent-tooling setup, after Ship review surfaces agent mistakes, in Operate when runbooks need encoding, or in Validate when you prototype agent workflows—especially when args are underspecified and you need o
Is build-skill safe to install?
It may guide writing files under your skills directory; review the Security Audits panel on this Prism page and inspect generated SKILL.md before granting broad filesystem access to agents.
SKILL.md
READMESKILL.md - Build Skill
# /build-skill Build one strong skill draft on purpose. This skill writes skills as operational briefs for capable senior engineers with no local context. Favor invariants, decision boundaries, evidence, and stop rules over shell choreography or ceremony. ## Args The args string should include: - the skill name - what the skill does - any modes, commands, or repo context that materially change the design If the request is underspecified, ask one clarifying question before proceeding. ## Core principles - Write for a capable senior engineer, not a shell automaton. - Frontmatter descriptions are for discovery. They should say when to use the skill, not summarize the whole workflow. - Use the smallest amount of process that still preserves quality. - Review feedback should protect invariants or sharpen decision boundaries, not automatically reintroduce procedural clutter. - Token efficiency matters. If detail is rarely needed, keep it out of the main body or load it on demand. ## Routing decisions Before drafting, classify: - **Scope**: user-level or project-level - **Target path**: the exact `SKILL.md` destination implied by that scope - **Rules encoding**: whether the skill primarily preserves governance, policy, or decision algebra rather than a normal workflow If any of those remain ambiguous after one clarifying question, stop and escalate. ## RED phase Establish the failing baseline before writing the skill. The baseline-failure exercise is mandatory when: - editing an existing skill - writing a skill that enforces rules, discipline, or decision boundaries - the request is motivated by observed agent failure, drift, or rationalization For a brand-new workflow skill with a clear spec and no observed failure history, a lighter RED phase is acceptable: identify at least one plausible failure mode before drafting. Capture: - what goes wrong without the skill - what a weak version of the skill would fail to prevent - what rationalizations or shortcuts the skill needs to resist ## Build flow 1. **Orient** - extract the skill name and purpose - classify scope, target path, and rules encoding 2. **Isolate** - if already in a worktree, continue - otherwise use `/isolate` before writing files 3. **Design** - use `/brainstorming` if the skill shape is still unclear after the initial clarification - keep it short; the goal is clarity, not a long discovery phase 4. **Write a plan** - write `ai-workspace/plans/build-skill-<name>.md` - include the skill spec, the RED baseline, target path, and what “good” means for this skill 5. **Review the plan** - run `/plan-review` - teach reviewers how to evaluate a good skill: - clear objective - clear invariants - evidence to gather - safe automatic paths - explicit stop boundaries - no penalty for avoiding shell choreography 6. **Draft one skill** - write one deliberate draft in the target style - do not run a default three-draft tournament 7. **Review the draft** - review against the RED baseline, invariants, and rationalizations - accept feedback that protects an invariant or clarifies a decision boundary - discuss feedback that mainly adds procedure without improving safety or clarity 8. **Refine or escalate** - revise until the skill is concise, discoverable, and safe - escalate instead of polishing forever when: - the request remains underspecified after one clarifying question - review finds an unresolved invariant failure - review disagreement is really a policy choice that repo context cannot settle - repeated revisions add process without improving safety or clarity 9. **Verify** - if project-level, confirm the skill is discoverable in th