update-skill

update-skill

skills/<library>/ An orchestration skill that makes the references / samples / scripts follow the latest version of the official documentation.

Usage

/update-skill zod          # 差分レポートのみ（既定: check）
/update-skill zod apply    # 差分を確認して更新まで適用

Argument	Required	Description
library	Required	Name of the library to update (e.g.: zod, hono）
mode	Optional	check(diff report only) or apply(apply up to update). Default: check

mode は check / apply Only one of these is accepted. If any other value is passed, do not proceed with the process and ask back for the correct value (the same validation exists on the reference-updater side, but main also rejects it so that invalid values are not passed downstream).

main (this skill itself) focuses on delegation, integration, and reporting, and delegates document research and file diff application to specialized Agents (.claude/rules/delegation.md compliant).

Flow

Step 1: Detect the differences

Launch **reference-updater (subagent_type: reference-updater, model: sonnet)** and have it detect the differences from the official documentation.

Parameters to pass:

Parameter	Content
library	Library name
skill_dir	skills/<library>/
mode	The received mode argument (default: check）

When the scope is wide (e.g., many categories), split the scope and launch reference-updater in parallel.For scope splitting, make sure all existing references categories are shared without omission (assign every category to one of the scoped jobs without fail, so that nothing is left out). This ensures that changes to existing categories references/ are always applied in one of the scoped executions (atmode=apply time).

However, scoped execution does not target samples/ scripts/ , soif the scope is split, regardless of which of the input mode が check・apply it is, in addition to the scoped execution, run the scope-unspecified (whole) reference-updater once with mode=check , detect the differences ofsamples/ scripts/ and include them in the report. This whole detection is part of Step 1 (difference detection), and must always be performed independently of whether to continue to Step 2 or the input mode. This whole check also serves as a safety net, and if a change to an existing category that was not assigned to any scoped job is detected, it is picked up by the later omission application.

Important: This whole run must always be mode=check(detection only).mode=apply would cause the whole run to re-diff and re-apply the references/ already applied by the scoped executions, double-editing the same file.references/ Application is handled only by the scoped executions, and the whole execution is for detection only (since reference-updater does not rewrite samples/ scripts/ regardless of mode, check is sufficient for detection).

Merge the "change category lists" from each scoped run and the overall run (check), and finalize the targets for the subsequent readme-indexer and the new/changed follow-up targets for Step 2.

Input mode=check In the case of, present to the user the diff report including the overall detection described above (coveringreferences / samples / scripts ) and terminate.

Step 2: Apply updates (when mode=apply)

reference-updater は mode=apply At the time of references/ のalso perform updates (Edit) of existing filesが、samples/ scripts/ changes ofdo not create new items. Among the follow-up work described in the diff report, delegate the following that reference-updater does not handle (since creation of new items is not performed on the reference-updater side, duplicate creation will not occur).

Creation of new items:

• A new references category → delegate to **reference-researcher (subagent_type: reference-researcher, model: sonnet)**. If there are multiple new categories, launch them in parallel with 1 Agent = 1 Category, and for each Agent pass base_url(the official documentation URL reported by reference-updater),scope= the relevant category,output_dir＝skills/<library>/references/<category>/ (same convention as create-skill Step 3. reference-researcher requires the default mode=full で base_url , so always pass it)
• New pages within an existing category → similarly delegate to reference-researcher . Because reference-updater does not Write new pages even when mode=apply and instead routes them to recommended actions (reference-updater Step 4 mode=apply rule 2), so that new pages are not left behind as report-only, launch it for the relevant category by passing base_url(the official documentation URL reported by reference-updater),scope= the relevant category,output_dir＝skills/<library>/references/<category>/ (since the default mode=full で base_url is required, always pass it).In this delegation, explicitly instruct "create only new pages (do not update existing files)"(reference-researcher action principle 4). Since content updates of existing pages have already been handled by the scoped reference-updater (mode=apply), do not let reference-researcher touch existing files and have it only create the missing new pages, preventing the same file from being double-edited by both Agents with different strategies
• A new samples use case → delegate to **sample-curator (subagent_type: sample-curator, model: sonnet)**. Parameters to pass: library, skill_dir（skills/<library>/）, base_url(optional)
• A new CLI/command → delegate to **script-collector (subagent_type: script-collector, model: sonnet)**. Parameters to pass: library, skill_dir（skills/<library>/）, base_url(optional)

Applying changes to an existing references category:

• Normally, scope splitting covers all categories, so changes to existing pages are already applied by each scoped run (mode=apply).
• As a safety net, if the overall check report showschanges to an existing category that was not assigned to any scoped job, then for that category additionally reference-updater を mode=apply・scope= applicable categoryand apply the changes (do not leave it in report-only mode). Since the scoped execution and the target category do not overlap, double application will not occur.

Following up on changes to existing samples / scripts(when reference-updater reports "update required"):

• An existing sample has become outdated due to an API change → delegate to sample-curator and have it regenerate the relevant use case (parameters to pass: library, skill_dir, base_url(optional).scope You may also narrow down the target use cases with
• An existing script has become outdated due to a CLI command change → delegate to script-collector and have it regenerate the relevant category (parameters to pass: library, skill_dir, base_url(optional))

If multiple tasks are needed, launch them in parallel.

Step 3: Regenerate the indexes and entry points

After updating, execute the following in order.

1. readme-indexer（subagent_type: readme-indexer、model: haiku） — have the references categories listed in the "change category list" of the reference-updater's update report, as well as the changed samples/ scripts/ の README.md indexes, regenerated (since reference-updater does not regenerate the README indexes at apply time, be sure to execute this here).For each changed category/directory, pass category_dir(e.g. skills/<library>/references/<category>/, skills/<library>/samples/, skills/<library>/scripts/) and launch it(readme-indexer: 1 launch = 1 category)
2. skill-author（subagent_type: skill-author、model: sonnet） — skills/<library>/SKILL.md have the directory tree and mapping table updated (only when categories have been added or deleted). Parameters to pass: library、skill_dir（skills/<library>/）、user-invocable(follow the values in the existing SKILL.md)

Step 4: Verify quality

Launch the following Agents to check quality. For all of them, pass skill_dir（skills/<library>/) to limit the verification target (if unspecified, the linter will scan all of skills/ and the validator's target directory will become undefined).

• reference-linter（subagent_type: reference-linter、model: haiku） — have it check that the references body text, samples/scripts body text, each README index, and SKILL.md frontmatter of the updated files conform to the format (parameters to pass: skill_dir）
• skill-structure-validator（subagent_type: skill-structure-validator、model: haiku） — have it check whether SKILL.md and the directory structure conform to skill-anatomy (parameters to pass: skill_dir）

Send the pointed-out issues back to the relevant Agent according to their content, and re-verify after fixing.

• references body text (defects in existing files) → reference-updater
• references body text (defects in new pages) → reference-researcher
• defects in samples body text → sample-curator
• defects in scripts body text → script-collector
• each category README.md index defects → readme-indexer
• SKILL.md の description(defects caused by hit rate, length, YAML # ) → description-optimizer
• defects in SKILL.md's tree, mapping table, and frontmatter other thandescription → skill-author

Step 5: Reflect in CLAUDE.md

If the skill's structure has changed significantly, such as by adding categories, call the update-docs skill and update the repository structure tree in CLAUDE.md.

Step 6: Commit (optional)

If the user instructs to commit, create-commit create a commit with the skill.

Verification

• Confirm that difference detection by reference-updater has completed
• When mode=apply: git diff skills/<library>/ confirm that the differences have been applied
• Confirm that the verifications by reference-linter and skill-structure-validator have PASSed
• Confirm that CLAUDE.md reflects the latest skill configuration (if there were configuration changes)

Notes

• .claude/ When editing under .claude/rules/dotclaude-via-temp.md follow _/dotclaude/ and do so via
• main itself does not directly read the official documentation, and always delegates to a specialized Agent

Related

Agents: reference-updater, reference-researcher, sample-curator, script-collector, readme-indexer, skill-author, reference-linter, skill-structure-validator

Rules: delegation, skill-anatomy, reference-template

Skills: update-docs, create-commit