skill-authoring

Files (2)

• SKILL.md
• testing.md · references/

SKILL.md (first lines)

# Skill Authoring

Project-only workflow skill for this repository. Follow it whenever a skill
is created, modified, moved, or removed.

## Define the skill first

Answer these before creating any files; they decide whether the skill is
worth building and where it belongs:

1. What task does the skill cover? Is it one coherent unit of work (not a
   grab-bag, not a sliver of a larger workflow)?
2. When should it trigger — including indirect phrasings a user might say
   without naming the domain?
3. What does the agent lack without it? If the agent already handles the
   task well, do not build the skill.

## Before writing anything

1. Load the `great-skill-writing` skill when it is available — it is the
   generic authoring layer this workflow builds on (value definition,
   description triggers, information hierarchy, leading words, pruning).
   `.agents/knowledge/skill-quality.md` records this repository's quality
   bar; it does not replace that layer.
2. Read `.agents/knowledge/skill-quality.md` — the quality bar every skill
   must meet (scoping, structure, spec limits, self-containment,
   description/body standards, instruction patterns, progressive
   disclosure, script rules).
3. Decide where the skill lives:
   - **Public skill** (distributable): `skills/<catalog>/<skill-name>/`.
     Pick the catalog from the list in `ARCHITECTURE.md` (Catalogs section)
     and read that catalog's `CONTEXT.md` for catalog-specific requirements,
     including which dependencies it grants (`## Dependencies`) and how it
     names skills (`## Naming`). Name the skill by the recommended shape in
     `.agents/knowledge/skill-quality.md` unless the catalog says otherwise.
   - **Project-only workflow skill** (serves this repo itself):
     `.agents/skills/<skill-name>/` as a real directory.
4. The `change-workflow` skill must already have placed the worktree on a
   dedicated branch and, for a behavior change, created and had approved the
   OpenSpec change `openspec/changes/<slug>/` with a delta spec for the
   skill's domain (`.agents/knowledge/spec-workflow.md`). The delta spec's
   scenarios are the behavioral test cases: triggering prompts for
   description scenarios, outcome tasks and rubric items for behavior
   scenarios. A change that alters no observable behavior needs no scenario
   and is a documentation change; a behavior change without a scenario
   means the delta spec is incomplete, not that the change is documentation.
5. Apply the subagent gate below. If it passes, read
   [references/testing.md](references/testing.md) and derive the behavioral
   tests from the scenarios into the change's `design.md` verification plan
   before editing. If it fails, do not read the reference; record the skipped
   behavioral tests and missing capability in that plan and in the handoff.

Done when: the target location is recorded and either the behavioral cases,
rubric, critical failures, and passing threshold are defined or the missing
subagent capability is recorded.

## Gate behavioral tests by subagent support

The gate passes when the invoking agent can dispatch clean-context subagents;
this is the only required capability. Do not maintain a framework allowlist or
denylist. If subagents are unavailable, do not load the reference or use the
authoring agent as a solver or grader; record the skipped tests and missing
capability in the handoff.

## Creating a public skill

1. Scaffold `skills/<catalog>/<skill-name>/SKILL.md` with `name` (must equal
   the directory name) and `description` frontmatter. Add `scripts/`,
   `references/`, or `assets/` only when a file is going into them. No
   README.md in the skill root; content in English; references and
   handoffs as `skill-quality.md ## Self-containment and dependencies`
   requires. While drafting, lint the skill in isolation:

   ```bash
   just check-skill skills/<catalog>/<skill-name>
   ```

2. Symlink it into the agent-visible directory (relative link, from repo
   root):

   ```bash
   ln -s ../../skills/<catalog>/<skill-name> .agents/skills/<skill-name>
   ```

3. Run `just gen-marketplace` to sync the skill into its catalog plugin's
   `skills[]` in `.claude-plugin/marketplace.json` (the validator enforces the
   list matches the catalog exactly). A brand-new catalog also needs a
   hand-added plugin entry —
   `{ "name": "<catalog>", "source": "./", "strict": false, "skills": [] }`
   with a `description` — before running the generator.
4. Add the skill to the catalog's `README.md` **and** `README.zh.md` tables.

## Creating a project-only skill

1. Create `.agents/skills/<skill-name>/SKILL.md` (real directory, no
   symlink, never listed in marketplace.json or catalog READMEs).
2. Repo path references are allowed here, but all other quality standards
   still apply.
3. The `openspec-*` directories there are generated
   (`spec-workflow.md ## Artifacts`); leave them to `just spec-sync`.

## Removing, moving, or renaming a skill

First trace every reference: `git grep -n <old-name>` across `skills/`,
`.agents/`, `.github/`, `openspec/`, and the root documents finds other
skills' handoffs, catalog `CONTEXT.md` routing, project skills, and specs
that name it. Fix all of them in the same change so no handoff points at a
name that no longer exists; a renamed skill's spec domain moves with it
through its OpenSpec change. Then remove/update the symlink in
`.agents/skills/`, the catalog README.md + README.zh.md entries, and run
`just gen-marketplace` to resync `.claude-plugin/marketplace.json` (remove a
plugin entry by hand only if its catalog became empty; a catalog left empty
follows the catalog row in `.agents/knowledge/harness-maintenance.md`). The
validator catches the mechanical part; it cannot see a stale name inside
prose.

## Finish

1. Walk the "Checklist before committing" in

From ryan-minato/skills, Apache-2.0.

More from ryan-minato/skills