Skill Creator

What good looks like (Ship Faster standard)

• SKILL.md

  : short and triggerable (routing + safety + I/O + output contract). Avoid long tutorials here.

• references/

  : deep docs loaded only when needed (progressive disclosure). Link directly from

  SKILL.md

  .

• scripts/

  : deterministic helpers for repetitive/fragile work (prefer this over re-writing code in chat).

• assets/

  : templates or files to copy (not meant to be loaded into context).

• Progressive disclosure + authoring principles:

  references/skill-design-principles.md

• Workflow structure patterns:

  workflows.md

• Output templates/patterns:

  output-patterns.md

Creation flow (recommended)

1. Collect trigger examples (real user phrases that should activate the skill).
2. Define the I/O contract (paths only) + required artifacts:
   • What files does the skill read?
   • What files must it write (plans, evidence, summaries)?
3. Implement reusable resources first:
   • add

     scripts/

     for deterministic steps
   • add

     references/

     for heavy documentation
   • add

     assets/

     for templates / boilerplate
4. Write

   SKILL.md

   last:
   • frontmatter

     description

     should include trigger phrases
   • body should be short and link out to the resources above
5. Validate + package (optional) using the scripts below.

Scripts

scripts/

Initialize a new skill folder

python scripts/init_skill.py <skill-name> --path <output-directory>

Validate a skill (frontmatter + basic conventions)

python scripts/quick_validate.py /path/to/<skill-name>

Sync catalogs/assets (manifest, skills-map, docs catalog)

python scripts/sync_catalog.py

Lint skills (compat + quality gates)

python scripts/skill_lint.py --check-generated

Package a skill into a distributable

.skill

zip (optional)

python scripts/package_skill.py /path/to/<skill-name> [output-directory]

Notes for Ship Faster contributors

• Prefer prefix naming:

  workflow-

  ,

  tool-

  ,

  review-

  ,

  mcp-

  ,

  skill-

  ,

  publish-

  .
• Keep side effects gated: write a plan first, ask for explicit confirmation, then execute, then verify.
• If you add/remove a skill, update the catalog:

  skills/manifest.json

  .

Claude Code: Slash Commands merged into Skills

• .claude/commands/<name>.md

  and

  .claude/skills/<name>/SKILL.md

  both create

  /<name>

• Existing

  .claude/commands/

  files keep working (no migration required)
• Prefer creating skills going forward so you can bundle

  references/

  ,

  scripts/

  , and use subagents

• disable-model-invocation: true

  - only user can invoke (good for side-effect workflows)

• user-invocable: false

  - hide from users; Claude-only background knowledge

• context: fork

  +

  agent: Explore|Plan|...

  - run skill in a subagent (good for research)

• allowed-tools

  - restrict tool surface when this skill is active

Archived full guide

• references/legacy-skill-creator.md