Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

craft-skill

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.

danielvm-git · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add danielvm-git/bigpowers --skill craft-skill

About this skill


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

RuleLimit
Max length1024 characters
VoiceThird person
ContentCapability + Use when … triggers only
ForbiddenWorkflow 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.

RuleLimit
Sentence length≤20 words per instruction sentence
VoiceImperative, active
Directive termsMUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
Banned modalsshould, might, could, may, consider, try, generally, typically
ScopeSKILL.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.

  1. 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?
  2. 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-
Read the complete source ↗