Remember

5. Skill Discovery and Synchronization

After successfully updating documentation, discover which skills may need updates by scanning skill files in .agents/skills/*/SKILL.md and .claude/skills/*/SKILL.md (whichever exist). When reading skill files, resolve symlinks to access the actual content rather than treating symlinks as empty or opaque files.

Discovery criteria — a skill is affected if it contains:

• Explicit references to the updated documentation file
• Content that covers the same topic or concept as the update
• Inline templates, code examples, or patterns related to the updated guideline
• Instructions or rules that may now be outdated or contradicted by the new documentation

If no skills are affected, skip this step.

For each affected skill, determine whether it is local or shared:

A skill is shared if it is a symlink pointing outside the current repo or was installed by a package manager and has not been modified locally. A skill is local if it was authored or edited in this repo. Symlinks between .claude/skills/ and .agents/skills/ within the same repo are internal bridges and do not affect this determination.

Local skills — edit directly:

• Update the skill's templates, examples, and instructions to align with the new documentation

Shared skills — report and offer to update:

• Report the affected shared skill and the specific inconsistency to the user

• Ask: "Shared skill <skill-name> is affected. Add repo-specific additions?"

• If the user confirms:

  1. Resolve the original shared skill path (the symlink target or CLI cache location where the shared skill was installed)

  2. Determine which layer to use:

     If .agents/skills/ directory exists:

     Create or update .agents/skills/<skill-name>/SKILL.md with repo-specific additions listed before the shared skill reference, so local rules take priority:

     ---
     name: <skill-name>
     description: <same description as the shared skill>
     allowed-tools: <same allowed-tools as the shared skill>
     ---
     
     ## Repo-specific additions
     
     - <the new convention or guideline>
     
     ## Shared skill
     
     Read and follow the shared skill at `<original-shared-skill-path>`.

     Then ensure .claude/skills/<skill-name>/SKILL.md is a symlink to .agents/skills/<skill-name>/SKILL.md:

     • If it is already a symlink to the correct path, no action needed
     • If it exists as a regular file, delete it and create the symlink
     • If it does not exist, create the symlink

     If .agents/skills/ directory does not exist:

     Create or update .claude/skills/<skill-name>/SKILL.md directly with the same structure (repo-specific additions before the shared skill reference).

• If the user declines, log the inconsistency in the final confirmation but take no action

6. Final Confirmation

Report all changes made:

• Documentation file(s) updated
• Skill file(s) updated (if any), with rationale explaining why each skill was identified as affected
• Summary of what was added or modified in each file

Guidelines

• Always read target files before modifying them
• Prefer adding to an existing section over creating a new one
• Keep entries concise; one to two sentences per guideline is ideal
• If the user's input is ambiguous, ask for clarification before writing
• Do not duplicate information that already exists in the target file
• When creating skill files, create the <skill-name>/ subdirectory if needed but do NOT create .agents/ or .agents/skills/ directories — only use them if they already exist