/sdlc:update-skill-doc

Generated from solutions/ontological/skills/update-skill-doc/SKILL.md.

Description

Refresh a single skill’s per-skill doc at docs/skills/.md from the current solutions/ontological/skills//SKILL.md. Reads the skill body and the house-style at solutions/ontological/skills/README.md, rewrites the doc (title, one-line summary, trigger, Mermaid flowchart of the skill’s steps and major branching/looping logic, notes), and commits on the current branch. Idempotent — re-running against an unchanged SKILL.md produces no diff.

Allowed tools

Read
Edit
Write
Bash
Skill

Source

/update-skill-doc

Usage:

/update-skill-doc <skill-slug> — refresh docs/skills/<slug>.md from solutions/ontological/skills/<slug>/SKILL.md. Slug is matched against solutions/ontological/skills/ directory names under the current repo root.

Project context (don’t re-derive every run):

Per-skill docs live at docs/skills/<slug>.md, one per skill in solutions/ontological/skills/. The house-style is canonical in solutions/ontological/skills/README.md — required shape, flowchart conventions, and a minimal example. Read that file every run. Don’t duplicate any of its prose inside this skill or inside the doc you write.
A warning hook (.claude/hooks/warn-skill-doc-drift.ts) flags drift when a SKILL.md is edited without its matching doc. This skill is the recovery action it points authors at.
The skill is single-slug. Batch mode over every skill is out of scope.

References:

${CLAUDE_PLUGIN_ROOT}skills/README.md — house-style for per-skill docs (title, summary, trigger, Mermaid flowchart, notes; flowchart conventions; minimal example).
${CLAUDE_PLUGIN_ROOT}skills/CLAUDE.md — skill-authoring conventions (don’t duplicate prose; reference canonical docs).
${CLAUDE_PLUGIN_ROOT}conventions/commit-messages.md — commit-message pattern for any model-generated message produced by this skill.

1. Resolve the slug

The user invokes /update-skill-doc <slug>. Resolve the slug against the repo:

Determine the repo root via git rev-parse --show-toplevel.
Check that <repo-root>/solutions/ontological/skills/<slug>/SKILL.md exists. If not, exit with a clear error naming the slug and listing the directories actually present under solutions/ontological/skills/. Do NOT write docs/skills/<slug>.md in this branch.
If the user omitted the slug entirely, exit with usage: usage: /update-skill-doc <slug>.

2. Read inputs

In parallel:

solutions/ontological/skills/<slug>/SKILL.md — the source of truth for what the doc must describe.
solutions/ontological/skills/README.md — the house-style. Required shape, flowchart conventions, the worked example.

Also read the existing docs/skills/<slug>.md if it exists — useful to preserve any notes that aren’t redundant with the SKILL.md and to keep the diff minimal when the SKILL.md hasn’t substantively changed.

3. Derive the doc content

From the SKILL.md, derive:

Title — # /<plugin>:<slug> matching the invocation form the skill’s body uses. (Most skills here are /sdlc:<slug>; this one is bare /update-skill-doc.) When the SKILL.md’s own H1 already encodes the prefix, mirror it verbatim.
One-line summary — a single sentence paraphrased from the description: frontmatter field. Tighten to one line if the description spans several. Keep it factual, not promotional.
Trigger — a single bold line **Trigger:** ... using the Usage block at the top of the SKILL.md. If the skill has multiple invocation forms, pick the canonical one and mention alternatives in parens.
Flowchart — a single fenced ```mermaid flowchart TD block. Map each numbered step in the SKILL.md to a node labelled with the step number and a short verb-phrase summary (e.g. S1[1. Resolve task file]). Diamond {...} nodes for decisions; back-edges for loops with a condition label; pill [/.../] nodes for terminal stdout markers (READY:, NEEDS-DEFINITION:, etc.) if the skill has any. Follow solutions/ontological/skills/README.md Flowchart conventions section literally — don’t reinvent shapes.
Notes — 2-6 short bullets covering anything the flowchart can’t carry: gotchas, references to canonical conventions (e.g. branch naming, commit-message pattern), atomicity guarantees, what the skill explicitly doesn’t do. Keep it tight.
Optional sections — add ## Outputs (with the skill’s stdout markers) only if the SKILL.md documents deterministic markers other skills key off of. Add ## Sub-skills invoked only if the SKILL.md meaningfully orchestrates /sdlc:* skills via the Skill tool.

Do NOT inline the house-style preamble inside the doc you write — each docs/skills/<slug>.md should contain only its own title, summary, trigger, flowchart, and notes. The README is the canonical home for the style itself.

4. Write the doc

Use the Write tool (or Edit if the doc already exists and you’re making targeted updates) to put the derived content into <repo-root>/docs/skills/<slug>.md.

After writing, run a diff against the pre-edit version (git diff -- docs/skills/<slug>.md). If the diff is empty, the regen was a no-op — skip Step 5 and report “no changes” on Step 6.

5. Commit

If the diff is non-empty:

Stage only the doc: git add docs/skills/<slug>.md.
Commit with the message docs(skills): refresh <slug> via sdlc commit create:
Terminal window
```
${CLAUDE_PLUGIN_ROOT}cli/sdlc commit create \
  --subject "docs(skills): refresh <slug>"
```
See ${CLAUDE_PLUGIN_ROOT}conventions/commit-messages.md.
Commit on whatever branch the user is on. This skill does not create branches or worktrees.

6. Report

Tell the user, in order:

The absolute path of the doc written.
Whether anything changed (updated / no changes — already in sync).
The commit SHA if a commit was made.

Notes

House-style. Don’t duplicate the per-skill doc style preamble inside the doc you write. See ${CLAUDE_PLUGIN_ROOT}skills/README.md — it’s the canonical home for the shape and the flowchart conventions.
Skill-authoring conventions. Don’t inline shared prose into multiple SKILL.md files. See ${CLAUDE_PLUGIN_ROOT}skills/CLAUDE.md.
Commit-message pattern. Author the commit with sdlc commit create. See ${CLAUDE_PLUGIN_ROOT}conventions/commit-messages.md.
Branch. This skill commits on the current branch — it does not create branches or worktrees. If the user wants the doc refresh in a PR, they’re responsible for the branch. See ${CLAUDE_PLUGIN_ROOT}conventions/branch-naming.md.
Idempotent. Re-running against an unchanged SKILL.md produces no diff and no commit.
Single-slug. Multi-skill batch mode is out of scope. If the user needs to refresh every doc, run this skill once per slug.
Recovery action for the drift hook. .claude/hooks/warn-skill-doc-drift.ts names this skill as the recovery step when it fires. Keep the hook’s message and this skill’s slug in sync.