| name | craft-skill |
| model | sonnet |
| description | Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle. |
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 — the 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.
Process
-
Gather requirements — ask user about:
- What task/domain does the skill cover?
- What specific use cases should it handle?
- Does it need executable scripts or just instructions?
- Any reference materials to include?
- What specs/ output does it produce (if any)?
-
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?
-
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, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
-
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.
-
Review with user — present draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more/less detailed?
-
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/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:
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 && echo OK || echo FAIL
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"
