update-skill-docs

name

update-skill-docs

description

Refresh a package's existing skill docs (Skill Body plus reference docs) when its API has changed — release prep, renamed or added members, obsolete sections, stale snippets or pitfalls. Use when making api changes in a project with AgentSkills.Sdk that need to be reflected in docs or when a Maintainer explicitly says "update the skill docs", "the docs are out of date", "refresh the docs for the new release", or when chained from the setup-agentskills-sdk skill because the repo's docs exist but are stale.

Update Skill Docs

Refreshes docs already feeding into AgentSkills.Sdk — the Skill Body (AgentSkillBodyFile) and reference docs (AgentSkillReferenceFiles) — so they match the package version being prepared. Update the drifted sections only; the skill's job is a targeted refresh, not a rewrite.

The body and reference templates live with the sibling Authoring Skill — read ../author-skill-docs/references/body-template.md and ../author-skill-docs/references/reference-doc-templates.md before step 5.

Hard rules

• Output is doc-file edits only. Never modify source code or the .csproj.
• Skill Body contains NO YAML frontmatter block. The SDK synthesizes name/description frontmatter at pack time.
• Never generate or edit XML doc comments in source files. Read them as input; never write them.
• Do not scan the codebase without consent (step 3). A prior instruction like "scan the code" counts as consent — record it — but the scan-tool choice still gets confirmed before scanning.
• Diff discipline — the core rule. Touch only sections the API change affects: snippets, entry-point tables, pitfall entries. Do not rewrite, restyle, or reorder sections the change did not touch. Preserve the existing structure and voice. If the docs need a structural overhaul rather than a refresh, say so and suggest the author-skill-docs skill instead.
• Never update against the wrong version. Anchor the refresh to the package version being prepared (step 2) and say which version the docs now describe when you hand over.

If the Maintainer signals urgency, batch the questions from steps 1–3 into a single message; do not skip any of them.

Steps

1. Determine mode and locate the existing docs

• Chained: invoked from the setup-agentskills-sdk skill (the conversation is already onboarding a project onto AgentSkills.Sdk; docs exist but are stale). Skip questions setup already answered (project, package id, doc sources).
• Standalone: invoked by name or by an update request. Read the project's .csproj for the wired sources: AgentSkillBodyFile, AgentSkillReferenceFiles, AgentSkillAssetFiles, AgentSkillScriptFiles. If none are set, scan the repo for the produced files (docs/skill-body.md, docs/quickstart.md, docs/api-overview.md, …) — excluding bin/, obj/, node_modules/, .git/.

No existing docs found → the flow belongs to author-skill-docs (sibling skill in this repo), not here. Say so and stop.

Done when: mode known, target project known, and every doc file to refresh is named, each with a wired-source or discovered-path provenance.

2. Establish the change set

Ask, in one batch:

1. What changed in the package since the docs were last updated — new or renamed APIs, changed signatures, removed features, new configuration?
2. What's the release/version being prepared (so the refresh anchors to it)?

If the Maintainer defers or is unsure, derive the change set yourself: release notes or changelog in the repo, then git log / git diff between the last tagged release and HEAD, filtering for public API files. The scan in step 4 confirms the change set against reality.

Done when: a named change set exists (interview answer or diff artifact) and the target package version is known.

3. Get scan consent and pick a scan tool

Ask permission to scan the codebase (skip the ask if consent was already given — see Hard rules). If declined, update from the interview alone and mark every new or changed snippet with <!-- unverified -->.

If granted, pick the most token-efficient tool that yields public signatures and XML doc comments, and confirm the choice with the Maintainer before scanning. Candidates, in typically-cheapest-first order — but the criterion wins over the order:

1. A code-index MCP server already connected to the session
2. LSP (document symbols / hover for signatures and XML doc comments)
3. An existing CLI that dumps API surface (run via Docker if repo rules require)
4. Plain Grep/Read over source files (always available)

Done when: consent recorded (yes/no) and, if yes, tool choice confirmed by the Maintainer.

4. Scan

Two passes, cheapest-first:

1. Public API surface: public types and members with signatures, focused on the change set from step 2 — verify the changed APIs and harvest XML doc comments (<summary>, <param>, <example>) for the refreshed sections.
2. Real usage patterns: mine README, samples/, and test projects for how the changed API is actually called.

Done when: every item in the change set is confirmed (or refuted) against the scan, and you can show one real, compiling-looking usage snippet per changed API.

5. Apply targeted edits

Against each located doc file, edit only the sections the change set affects:

• Stale snippets → replace with scanned equivalents.
• Entry-point tables → add, remove, or rename rows.
• Pitfalls → drop entries that no longer hold; add new ones sourced from the change set or scan (test edge cases, guard clauses that throw).
• <!-- unverified --> markers → remove only where the scan now verifies the snippet; leave or add the marker everywhere else.
• Reference docs → same discipline, one concern per doc, respecting the templates in the sibling Authoring Skill.

Keep the body under ~150 lines; if the refresh needs more than ~half the body's lines, stop and propose author-skill-docs for a rewrite instead.

Done when: every changed item from step 2 is reflected in the docs, untouched sections are byte-identical to before, and each new or changed snippet traces to the scan or carries <!-- unverified -->.

6. Review and hand off

Show the Maintainer a change summary: files touched, sections changed per file, and the package version the docs now describe. Explicitly list what was intentionally not touched (the diff discipline proof). Apply requested edits.

Then, by mode:

• Chained: hand back the refreshed file paths to the setup-agentskills-sdk flow so it can verify the pack. Do not edit the .csproj yourself.
• Standalone: done — the wiring already exists; remind the Maintainer that dotnet pack picks up the changes on the next release build.

Done when: Maintainer accepted the refresh and the change summary matches the actual edits.

Common mistakes

Mistake	Fix
Rewriting unchanged sections while updating one snippet	Diff discipline — touch only what the change set affects; show what stayed untouched
Reordering or restyling content that drifted on its own	The refresh is content-only; propose author-skill-docs for structural work
Adding frontmatter to the body	Delete it — the SDK owns frontmatter
Editing XML doc comments "while you're in there"	Never. Docs output only; shipping XML docs is the SDK's job (AgentSkillIncludeXmlDocs)
Scanning before asking	Consent first, tool confirmation second, scan third
Updating against the wrong release	Anchor to the prepared version in step 2; state the version in the hand-off
Keeping <!-- unverified --> off new snippets	New content without scan provenance carries the marker until verified