| name | manage-skill |
| description | Create, update, evaluate, and optimize skills under this repository's `.claude/skills/`, wrapping Anthropic's official `skill-creator` methodology and layering this repo's conventions on top (English-canonical SKILL.md + mandatory `SKILL.ja.md` translation pair, dense "pushy" description frontmatter, AGENTS.md scope + hard-protected paths, eval artifacts kept out of version control). This is the single entry point for ANY change to an existing skill under `.claude/skills/`; ALWAYS use it before hand-editing a `SKILL.md` or `SKILL.ja.md`. Use this WHENEVER the user wants to update / modify / change / edit / fix / improve / refactor / rename / extend / adjust / tune an existing skill — its steps, `description`, frontmatter, or behavior — or to build a new skill, author/scaffold a `/<name>` command, turn a repeated workflow into a skill, tune a skill's triggering description, or run evals/benchmarks on a skill — even if they don't say the word "skill-creator". Japanese triggers also apply, e.g. 「スキルを更新したい」「スキルを修正して」「このスキルの手順 / description / 挙動を変えて」. Do NOT use it for editing canonical docs (`docs/**`, per-package `README.md` — those have `sync-readme` / `canonicalize-doc` / `back-prop`), other AI-tool configs (`.cursor/`, `.gemini/`, Copilot), or generated files. |
| argument-hint | [skill-name] [--update|--new|--optimize] |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, Skill, Agent |
Manage Skill
You have been invoked via /manage-skill. Argument string: $ARGUMENTS.
This skill authors and maintains skills under .claude/skills/ for this repository. It is a
thin wrapper: the methodology (draft → test → review → improve → optionally optimize the
description) comes from Anthropic's official skill-creator skill, and this file layers the
repository's own conventions on top so the produced skill fits in alongside commit, new-env,
canonicalize-doc, and the rest.
A Japanese reference translation of this skill is available at SKILL.ja.md in the same directory
(not loaded as a skill; for human reference only).
When to Use
Use this skill when the user wants to:
- Create a brand-new skill /
/<name> command, or turn a repeated workflow from the current
conversation into one.
- Update, modify, improve, refactor, rename, extend, or fix an existing skill under
.claude/skills/ — this is the entry point for any such change, used before hand-editing a
SKILL.md / SKILL.ja.md.
- Optimize a skill's
description for better triggering, or run evals/benchmarks on a skill.
Do NOT use it for:
- Editing canonical docs (
docs/**, per-package README.md) — those have their own flows
(sync-readme, canonicalize-doc, back-prop).
- Other AI-tool configs (
.cursor/, .gemini/, .github/copilot-instructions.md) — out of scope
per AGENTS.md.
Scope note (AGENTS.md)
AGENTS.md normally treats .claude/** as out of scope. Invoking this skill is the explicit user
instruction that relaxes that — but only for .claude/skills/**, and only for the duration of this
run. The hard-protected paths from AGENTS.md stay protected even here: never touch AGENTS.md,
generated files (**/*.gen.go, *.sql.go, *_mock.go, **/openapi.gen.yaml), generated docs/
content, or anything under permissions.deny.
Step 0 — Ensure and load the official methodology (do this first)
The official skill-creator is the source of truth for the how. Operate on the assumption that it
is present: it is declared at project scope in this repo's .claude/settings.json, so a trusted
clone already has it. If it is missing, ensure it via the repo-level plugin bootstrap:
bash .claude/scripts/bootstrap-plugins.sh
The bootstrap declares the claude-plugins-official marketplace and enables the official plugins this
repo depends on (skill-creator, feature-dev) at project scope. It is idempotent; re-running is a
no-op. Newly enabled plugins load on the next session, when skill-creator also becomes invocable as
/skill-creator — but this wrapper does not depend on that; it reads the file by path so it works in
the same session.
Read that SKILL.md in full (the path the script prints; discover it with the glob below if needed):
ls ~/.claude/plugins/marketplaces/*/plugins/skill-creator/skills/skill-creator/SKILL.md
Everything it says about Creating a skill, Running and evaluating test cases, Improving the
skill, Description Optimization, blind comparison, and packaging applies verbatim. Its bundled
resources live next to it and are used as-is:
scripts/ — aggregate_benchmark, run_loop (description optimizer), package_skill, etc. Run
them from the official skill's directory; do not reimplement them.eval-viewer/generate_review.py — the review viewer. Always use it; never hand-write review HTML.agents/ (grader.md, comparator.md, analyzer.md) and references/schemas.md.
If the bootstrap fails (e.g. no network, claude CLI missing), report the failure to the user and ask
whether to proceed with the methodology summarized inline (draft → test → review → improve) instead of
aborting.
The repository overlay (this is what the wrapper adds)
Follow the official process, but apply these repo-specific rules wherever they differ. On conflict,
these win, because a skill that ignores them won't fit this repo.
1. Placement and structure
- New skills live at
.claude/skills/<name>/SKILL.md, <name> in kebab-case matching the name:
frontmatter. Look at neighbors first (commit, new-env, canonicalize-doc, the scaffold-*
family, the integrator arch-check / back-prop) and prefer editing/extending an existing skill
over adding a near-duplicate.
- Bundled resources (
scripts/, references/, assets/) follow the official anatomy when needed.
Keep SKILL.md under ~500 lines and push detail into references/ with clear pointers.
2. Frontmatter conventions (match the existing skills)
name: kebab-case, equal to the directory name.description: one dense paragraph, English, following the official "pushy" triggering guidance
(state what it does AND concrete when-to-use contexts, plus explicit when NOT to trigger). Study
the descriptions of commit / new-env for the density and tone this repo uses — match it.- Optional:
argument-hint and allowed-tools when the skill is a /command that takes args or runs
a fixed tool set (see commit for the pattern). Omit them when not needed (most skills do).
3. Language rules (CLAUDE.md)
SKILL.md is English canonical — its body is written in imperative English, like every existing
skill here. Do not write the canonical SKILL.md in Japanese.- But the skill's runtime behavior must obey
CLAUDE.md: all user-visible output the skill produces
(responses, generated code comments, test case names, PR/commit text) must be Japanese. When
authoring a skill, bake that requirement into its instructions.
4. Mandatory Japanese translation pair
Every skill in this repo ships a SKILL.ja.md reference translation next to SKILL.md. This is not
optional here. After the canonical SKILL.md is finalized (create) or changed (update):
- Chain the
canonicalize-doc skill to produce/sync SKILL.ja.md from the canonical SKILL.md.
- The translation carries the standard sync-note header and is not itself loaded as a skill. Confirm
the pair is in sync before considering the task done.
5. Eval artifacts stay out of version control
The official process writes a <skill-name>-workspace/ with iteration/eval dirs, benchmarks, and
viewer output. A sibling of the skill directory would land inside the tracked .claude/skills/**.
Override the location: put the workspace under the repo's gitignored tmp/ (e.g.
tmp/manage-skill/<skill-name>-workspace/), consistent with this repo's work-artifact convention
(plans/artifacts live outside git; tmp/ is ignored). Never commit eval runs, benchmarks, feedback
JSON, or viewer HTML.
6. Reuse repo patterns when they fit the skill's shape
- If the new skill fans out read-only analysis across layers, mirror the integrator + per-layer
subagent pattern (
arch-check / back-prop spawn *-auditor-* / *-detector-* agents in
parallel; the integrator does the single-threaded writes). Reuse existing subagent types rather than
inventing new ones where possible.
- If the skill has a deterministic multi-step flow gated on user choices, use
AskUserQuestion for the
gates like new-env / commit do, rather than free-text prompts.
- Read the target layer's
README.md / docs/ at runtime as the source of truth (the arch-*,
test-review, scaffold-* skills all do this) instead of hardcoding rules that will drift.
Creating a new skill
Run the official Creating a skill flow (Capture Intent → Interview → Write SKILL.md → Test Cases),
then apply the overlay: correct placement, matching frontmatter/description density, English-canonical
body, and the eval workspace under tmp/. When the draft stabilizes, generate SKILL.ja.md via
canonicalize-doc.
Updating an existing skill
- Confirm which skill (
.claude/skills/<name>/). Preserve its name and directory unchanged.
- Unlike an installed plugin skill, repo skills are writeable in place — edit them directly under
.claude/skills/<name>/; there is no read-only copy-to-/tmp dance.
- For the eval baseline, snapshot the pre-edit skill per the official guidance (into
tmp/), so
before/after can be compared.
- After editing, re-sync
SKILL.ja.md via canonicalize-doc — an updated SKILL.md with a stale
Japanese pair is drift.
Evaluating / optimizing
Use the official test-run, benchmark, viewer, and Description Optimization flows unchanged, with
two adaptations: workspaces go under tmp/ (§5), and for the description optimizer pass the model ID
powering this session (see the environment/system prompt) so triggering matches production.
Definition of Done
- The official
skill-creator resolved (project-scope plugin; ensured via the plugin bootstrap if
missing) and its methodology is loaded.
.claude/skills/<name>/SKILL.md present, kebab name = dir, dense English "pushy" description.SKILL.ja.md generated/synced from the canonical SKILL.md and in sync.- No eval artifacts committed (workspace under gitignored
tmp/).
- No hard-protected path touched; only
.claude/skills/** modified.
- The user has reviewed outputs (viewer or inline) and is satisfied, per the official loop.
