craft-skill

Craft Skill

HARD GATE — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running sync-skills.sh. Generated .cursor/rules/ and .gemini/ artifacts MUST match the source SKILL.md.

CSO Description Discipline (e45s02)

The YAML description is the Catalog Selection Object — the only field agents see when picking a skill.

Rule	Limit
Max length	1024 characters
Voice	Third person
Content	Capability + Use when … triggers only
Forbidden	Workflow steps, phase chains, numbered lists, → verify:, HARD GATE prose

Move process detail into the SKILL.md body or REFERENCE.md — never into description.

Agentic STE body discipline (e79s02)

Skill-body instructional prose MUST follow AGENTIC-STE.md.

Rule	Limit
Sentence length	≤20 words per instruction sentence
Voice	Imperative, active
Directive terms	MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
Banned modals	should, might, could, may, consider, try, generally, typically
Scope	SKILL.md body only — not YAML description, not terse-mode output

HARD GATE — Do NOT merge a new or edited skill until bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md exits 0. Fix violations before sync-skills.sh.

Process

1. Gather requirements — ask user about:

   • What task/domain does the skill cover?
   • Which use cases must the skill handle?
   • Does it need executable scripts or just instructions?
   • Any reference materials to include?
   • What specs/ output does it produce (if any)?

2. Verify Principles — Ensure the skill aligns with PRINCIPLES.md:

   • Is it atomic (verb-noun)?
   • Is it "deep" (simple interface, complex internal logic)?
   • Does it include Hard Gates?
   • Is it verifiable with a .feature file?

3. Draft the skill — create:

   • SKILL.md with concise instructions (see REFERENCE.md for template)
   • Additional reference files if content exceeds 100 lines
   • Utility scripts if deterministic operations needed

   Auto-skill from library README: When user provides a library README or API docs URL, extract triggers and HARD GATEs. Draft verify commands and specs/ output into SKILL.md. Do NOT invent APIs not in the source.

4. Add model: frontmatter (haiku | sonnet | opus) per model-profiles.md.

STREAM CONTINUITY — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.

5. Review with user — present draft and ask:

   • Does this cover your use cases?
   • Anything missing or unclear?
   • Does any section need more or less detail?

6. Completion-honesty gate (HARD GATE — e45s02) — Before declaring done:

   • Run bash scripts/validate-skill-description.sh skills/<name>/SKILL.md — must exit 0
   • Run bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md — must exit 0 (e79s02)
   • Run bash scripts/sync-skills.sh — must complete without error
   • Run bash scripts/run-skill-verify.sh <name> if the skill defines a verify command
   • Show terminal output for each — narration without evidence is rejected

Naming Rules

Every skill name must be a two-word verb-noun pair. See REFERENCE.md for full rules, examples, and documented exceptions.

specs/ Output

If the skill produces written output, it goes in specs/ at the project root. Document the output file path in the skill body and in CONVENTIONS.md's output files table.

Review Checklist

After drafting, verify:

• [ ] Name is a two-word verb-noun pair (or follows grill-me exception)
• [ ] Description < 1024 chars, triggers only, no workflow-summary leakage
• [ ] Description includes triggers ("Use when...")
• [ ] SKILL.md under 100 lines
• [ ] No time-sensitive info
• [ ] Consistent terminology with CONVENTIONS.md
• [ ] specs/ output documented if applicable
• [ ] validate-skill-description.sh exits 0
• [ ] validate-agentic-ste.sh --strict exits 0 (e79s02)
• [ ] sync-skills.sh run to propagate to Cursor/Gemini
• [ ] bash scripts/validate-skill-catalog.sh passes for the new skill (HARD GATE — completion honesty)

HARD GATE — Do NOT declare the skill done until bash scripts/validate-skill-catalog.sh --strict --skill <name> exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and → verify: command.

Verify

→ verify: bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md

---

Craft Skill — Reference

Naming Rules (full)

Every skill name must be a two-word verb-noun pair:

• First word: a verb (survey, model, define, develop, audit…)
• Second word: a noun from PMBOK 6 / Agile vocabulary (context, domain, language, tdd, code…)
• Pronounceable in any language, searchable, no noise words, no encodings
• Exception precedent: grill-me — kept for recognizability

Good: survey-context, audit-code, validate-fix Bad: context-surveyor, code-auditing-skill, fix-validator

Any new naming exception requires an entry in CONVENTIONS.md before the skill is published.

Skill Structure

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.sh

SKILL.md Template

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

Description Requirements

The description is the only thing your agent sees when deciding which skill to load.

Format:

• Max 1024 chars
• Write in third person
• First sentence: what it does
• Second sentence: "Use when [specific triggers]"

Good example:

Investigate a bug by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, or mentions "triage".

When to Add Scripts

Add utility scripts when:

• Operation is deterministic (validation, formatting)
• Same code would be generated repeatedly
• Errors need explicit handling

When to Split Files

Split into separate files when:

• SKILL.md exceeds 100 lines
• Content has distinct domains
• Advanced features are rarely needed

sync-skills.sh Propagation

After adding a new skill directory with SKILL.md, run scripts/sync-skills.sh from the bigpowers repo root. This automatically generates:

• .cursor/rules/<name>.mdc — for Cursor
• .gemini/extensions/bigpowers/skills/<name>/SKILL.md — Agent Skill
• .gemini/extensions/bigpowers/commands/<name>.toml — Slash Command
• .gemini/extensions/bigpowers/commands/prompts/<name>.md — Command Prompt
• Updated gemini-extension.json

verify: bash scripts/sync-skills.sh 2>&1 | grep "skills synced"