new-skill

Author a new codeArbiter skill: prove the gap is real, get the spec approved, then write it.

What it does

The only permitted entry to creating a new codeArbiter skill. It hands off to the skill-author skill, which drives the whole job through five gated stages: proving the gap, scoping it, authoring the content, a self-review pass, and finally wiring in the routing entry — the INDEX.md line that actually makes the new skill reachable. Nothing gets written before an existing skill or agent is shown not to already handle the need, and nothing is considered done until the result has its own gates, hard rules, and a route pointing to it.

Name the skill in verb-noun form ("dependency-review"), not as a loose description ("the thing that checks packages") — that shape is what the authoring phase expects.

Usage

/ca:new-skill <verb-noun skill name>

The name argument seeds the gap-evidence phase; the spec that phase produces is what gets approved before any file is written.

Example

> /ca:new-skill "release-notes-linter"

Phase 1 (gap evidence): checked existing skills/agents — no coverage found for
release-notes format linting.
Phase 2 (scope): drafting spec for approval...

Spec: release-notes-linter
  Routes from: /ca:release (post-changelog-render)
  Gates: 2 (format check, broken-link check)
Approve this spec? y

When to reach for it

A one-time action belongs in /ca:feature or a plain command definition, not a new skill; if an existing skill nearly covers the need, extend it via /ca:feature instead. “Do we even need a skill here?” is a question for /ca:btw.

Gates

Gate	When	Effect
gap evidence	before any skill content is written	the gap must be proven uncovered by an existing skill or agent — nothing is authored speculatively
spec approval	before authoring begins	the user must sign off on the skill’s spec first

Source

Source — plugins/ca/commands/new-skill.md (v2.9.1)

---
description: Author a new codeArbiter skill: prove the gap is real, get the spec approved, then write it.
argument-hint: "<verb-noun skill name>"
---

# /ca:new-skill — author a skill

The only permitted entry to creating a skill. Nothing is written until the gap is proven uncovered — skills are not created speculatively. Name the skill in verb-noun form (`"dependency-review"`), not as a description (`"the thing that checks packages"`).

## Flow

Routes to the `skill-author` skill, which owns the work end to end through its five gated phases — gap
evidence, scope, authoring, self-review against the v2 house style, and routing integration (the
`INDEX.md` + routing-table entry that makes the new skill reachable). The phase definitions live in the
skill; this command does not restate them. Nothing is authored until an existing skill or agent is
proven not to cover the need; nothing ships until the new skill carries gated phases, hard rules, and
its routing entry.

## Routes to

`skill-author` (`${CLAUDE_PLUGIN_ROOT}/skills/skill-author/SKILL.md`) — all five phases.

## When NOT to use

- A one-time action → `/ca:feature` or a command definition.
- An existing skill nearly covers it → extend that skill via `/ca:feature`.
- "Do we even need a skill here?" → `/ca:btw`.

## Hard gate

MUST prove the gap is real in Phase 1 before writing any skill content. MUST get user approval on the
spec before authoring. MUST NOT create a skill that duplicates an existing skill's purpose — surface
the overlap instead. Skill files live only under `${CLAUDE_PLUGIN_ROOT}/skills/<name>/`.

View in repo