Update Skill

Incrementally update AI documentation without a full regeneration. Two distinct modes:

• add — introduce a new concept into the right doc files for each target agent
• change — propagate an evolved or removed concept across every existing AI doc file

Note: This skill uses text-based prompts instead of AskUserQuestion due to a known bug where AskUserQuestion auto-completes inside plugin skills (GitHub #29547, #29733).

---

Step 1: Determine Mode

Parse $ARGUMENTS:

• add → jump to Step 2a: Add Mode — Gather Concept
• change → jump to Step 2b: Change Mode — Gather Concept
• Anything else or empty → ask the user:

Which type of documentation update do you need?

1. Add — introduce a new concept, rule, or convention
2. Change — update or remove something that already exists

Enter 1 or 2:

Record the mode before proceeding.

---

Step 2a: Add Mode — Gather Concept

Present the following questions one at a time and wait for the user's response before proceeding to the next question.

Question 1 — Describe the concept:

Present the following to the user and wait for their response:

Describe the concept you want to add. Be specific — include the rule, why it exists, and any forbidden alternatives.

Examples:
- "Always use Zod for runtime validation. Never use manual type assertions or yup."
- "All API calls must use the generated client in src/api/generated/. Never use fetch() directly."

Wait for the user to respond before proceeding. Record the full description verbatim.

Question 2 — Which agents:

Present the following options to the user and wait for their response:

Which agents should this apply to?

1. Claude Code only
2. Cursor only
3. Codex CLI only
4. All agents (Claude Code + Cursor + Codex)
5. Let me decide for you (skip to analysis)

Enter the number of your choice:

Wait for the user to respond before proceeding. Parse their response to determine the selection.

Question 3 — Scope (optional):

Present the following to the user and wait for their response:

Does this rule apply everywhere, or only within specific files/directories?

Enter a path or glob scope (e.g., "packages/frontend" or "*.test.ts"), or press Enter to skip for global scope:

Wait for the user to respond before proceeding. If the user specifies a scope, record it as the path/glob scope.

---

Step 3a: Add Mode — Analyze and Suggest Doc Types

Use the concept description and scope to determine the best documentation placement. Apply the decision logic from ${CLAUDE_PLUGIN_ROOT}/reference/decision-guide.md.

Classification logic:

Concept characteristic	Best doc type(s)
Always-true coding standard (no steps, just a rule)	Rule file + mention in CLAUDE.md
Multi-step workflow invoked repeatedly	Skill
Single automation / shortcut	Command
Must fire automatically on every write	Hook
Scoped to specific files	Scoped rule (with paths:/globs:)
Needs to be excluded from AI context	Ignore file or deny rule
Complex enough to need isolation from main AI	Agent
Applies project-wide, cross-session	CLAUDE.md (brief) + rule file (detail)
Team-wide convention	CLAUDE.md + AGENTS.md + Cursor MDC
Personal preference only	CLAUDE.local.md

Token efficiency check before suggesting:

• Is this concept already documented anywhere? (Grep for key terms across all AI docs)
• If found, does it need updating rather than adding? (If yes, switch to Change mode)
• Would this concept fit naturally within an existing rule file? (Prefer addition over new file)

Build the suggestion and present it in this format:

## Suggested Documentation Plan

**Concept:** [one-sentence summary of the concept]

### Files to Create or Modify

| File | Action | Reason |
|------|--------|--------|
| .claude/rules/[topic].md | Create | Persistent coding standard → rule file |
| CLAUDE.md | Modify (add 1-line reference) | Cross-session memory |
| .cursor/rules/[topic].mdc | Create | Cursor equivalent with MDC format |
| AGENTS.md | Modify (add section) | Codex CLI coverage |

### Token Efficiency Notes
- [e.g., "This fits in the existing api-patterns.md rule — no new file needed"]
- [e.g., "CLAUDE.md reference only — detail stays in rule file for progressive disclosure"]

Proceed with this plan? (yes / adjust / cancel)

Wait for confirmation before writing any files.

---

Step 4a: Add Mode — Apply Changes

Generate or modify each file in the approved plan. Apply token efficiency rules throughout.

Token Efficiency Enforcement (Mandatory)

Before writing any content, check and enforce:

1. Progressive disclosure (from ${CLAUDE_PLUGIN_ROOT}/reference/best-practices.md):

   The goal is not hitting a line count — it is ensuring only relevant context loads for any given task. CLAUDE.md gets one-line references; detail lives in rule files. Rough typical ranges for orientation:

   File Type	Typical Range
   CLAUDE.md (root)	100–200 lines
   Package CLAUDE.md	80–150 lines
   Always-applied rule	20–50 lines
   Topic rule file	50–200 lines
   Cursor alwaysApply MDC body	Keep brief — loads every interaction
   Cursor topic MDC	30–100 lines
   Root AGENTS.md	Concise overview
   Nested AGENTS.md	30–80 lines

   If a file is growing unwieldy, suggest extracting sections into dedicated files and cross-referencing from the main file.

2. No verbatim duplication across files. The same rule must not appear word-for-word in CLAUDE.md, a rule file, and a Cursor MDC. Use a single authoritative location and cross-reference from others.

3. Progressive disclosure. CLAUDE.md gets one line + a reference. Detail lives in the rule file.

4. Imperative voice only. "Always X" / "Never Y" — not "you should" or "try to".

5. One DO/DON'T code example per new rule. No exceptions — rules without examples are not actionable.

Claude Code Rule File (Create or Append)

If creating a new rule file:

# [Topic] Rules

[One sentence explaining why this rule exists — the "why" that helps the AI generalize.]

## Always
- [Rule in imperative voice]

## Never
- [Forbidden alternative]

\`\`\`[language]
// ✅ DO
[concrete correct example with real project file references if possible]

// ❌ DON'T
[concrete forbidden example]
\`\`\`

Why: [one sentence rationale]

Add paths: frontmatter if the rule is scoped to specific directories:

---
paths:
  - packages/frontend/src/**
---

If appending to an existing rule file:

• Read the current file, count lines
• If the file is already covering many distinct topics and adding more would make it unwieldy: suggest extracting a section instead
• Append after the last existing rule section, before any "Critical Rules" section at the end
• Keep the new addition under 30 lines unless the concept requires more

CLAUDE.md Addition (One-Line Reference)

Find the most relevant existing section in CLAUDE.md and add a one-liner:

**[Short concept name]**: [10-word summary]. See `.claude/rules/[topic].md`

Never expand CLAUDE.md with full rule detail — it must stay brief.

Cursor MDC File (Create or Append)

Convert from the Claude rule format using these rules (from ${CLAUDE_PLUGIN_ROOT}/reference/cross-tool-mapping.md):

1. Add YAML frontmatter:

   ---
   description: [Topic-specific description with keywords for AI discovery]
   alwaysApply: [true if global, false if scoped]
   globs:                        # only if scoped
     - [glob patterns]
   ---

2. Convert emphasis:

   • ## Always → **ALWAYS:**
   • ## Never → **NEVER:**
   • Preserve all code examples as-is

3. Body must stay under 25 lines for alwaysApply: true rules. If content is longer, set alwaysApply: false and add a keyword-rich description so the AI discovers it.

AGENTS.md Addition (Section or Line)

Find or create the relevant section in AGENTS.md:

## [Topic]

✅ [Rule in positive form]
❌ Never [forbidden alternative]

\`\`\`[language]
# ✅ DO
[example]

# ❌ DON'T
[example]
\`\`\`

For one-liner additions to an existing section, just append the ✅ / ❌ lines.

---

Step 2b: Change Mode — Gather Concept

Present the following questions one at a time and wait for the user's response before proceeding to the next question.

Question 1 — What changed:

Present the following to the user and wait for their response:

Describe what changed. Include both the old concept and the new replacement (or state 'removed' if it was dropped entirely).

Examples:
- "We switched from Jest to Vitest. All references to jest, jest.config, and @jest/globals should be updated."
- "We no longer use DateUtils — we switched to dayjs. Remove all DateUtils rules and add dayjs rules."
- "The color brand-primary is now called primary. All color rules need updating."

Wait for the user to respond before proceeding. Record:

• OLD_CONCEPT: the term, pattern, or instruction being replaced
• NEW_CONCEPT: what replaces it (or "REMOVED" if dropped)

Question 2 — Key search terms:

Present the following to the user and wait for their response:

What exact terms should I search for? Enter them comma-separated.

Example: "DateUtils, dateUtils, date-utils, useDateFormatter"

Wait for the user to respond before proceeding. Record all terms as a list for the scan phase.

---

Step 3b: Change Mode — Scan All AI Docs

Scan every AI documentation file in the project for the old concept.

Files to scan (check for existence first, then read):

Claude Code:

• CLAUDE.md
• packages/*/CLAUDE.md
• apps/*/CLAUDE.md
• .claude/rules/*.md
• .claude/skills/*/SKILL.md
• .claude/agents/*.md
• .claude/commands/*.md
• .claude/settings.json
• CLAUDE.local.md

Cursor:

• .cursor/rules/*.mdc
• .cursorrules (legacy)
• .cursorignore

Codex CLI:

• AGENTS.md
• packages/*/AGENTS.md
• apps/*/AGENTS.md
• .codex/config.toml
• .codexignore
• .agents/skills/*/SKILL.md

Scan method:
Use Grep with each search term across the AI doc directories. For each match, record:

• File path
• Line number(s)
• The matching line(s) with context (1 line before, 1 line after)

Group results by file.

---

Step 4b: Change Mode — Present Change Plan

Present a structured change plan before touching any files.

## Change Plan

**Old Concept:** [OLD_CONCEPT]
**New Concept:** [NEW_CONCEPT]

### Files to Modify

**CLAUDE.md** (3 matches)
  Line 42: `Always use DateUtils.parseDate() for parsing dates`
           → `Always use dayjs() for parsing dates`
  Line 78: `See .claude/rules/date-handling.md for DateUtils patterns`
           → `See .claude/rules/date-handling.md for date handling patterns`
  Line 112: `import { DateUtils } from '@/utils/dateUtils'`
            → `import dayjs from 'dayjs'`

**.claude/rules/date-handling.md** (6 matches)
  [full list of line-by-line changes]

**.cursor/rules/date-handling.mdc** (4 matches)
  [full list]

**AGENTS.md** (2 matches)
  [full list]

### Files with No Matches (no changes needed)
- .claude/settings.json
- .cursor/rules/general.mdc

---
Total: [N] files to modify, [M] individual line changes

Proceed? (yes / review each file individually / cancel)

Wait for explicit confirmation before applying any changes.

---

Step 5b: Change Mode — Apply Changes Atomically

Apply all approved changes file by file. For each file:

1. Read the full current content
2. Apply all changes for that file (do not apply changes one-at-a-time with multiple reads)
3. Write the updated file
4. Verify the changes applied correctly (re-read a sample)

Replacement rules:

• Prefer Edit over Write for surgical changes
• Replace occurrences in code examples AND in prose
• Update import paths, class names, function names, and config references
• When removing a concept entirely: delete the full rule block, not just the term

Token efficiency check after changes:

• If any file now feels unwieldy or covers too many distinct topics: suggest extracting sections into dedicated files
• If any file now has orphaned cross-references: fix them
• If removing a concept leaves a rule file nearly empty (< 10 lines): suggest deleting the file

---

Step 6: Verify and Report

After all changes are applied, output a structured summary.

For Add Mode:

## Update Complete — Concept Added

**Concept:** [one-sentence summary]
**Agents Covered:** [list]

### Files Modified or Created
| File | Action | Lines Changed |
|------|--------|---------------|
| .claude/rules/[topic].md | Created | +[N] lines |
| CLAUDE.md | Modified | +1 line (reference) |
| .cursor/rules/[topic].mdc | Created | +[N] lines |
| AGENTS.md | Modified | +[N] lines |

### Token Efficiency Checks
- [ ] No verbatim duplication across files
- [ ] Progressive disclosure pattern used (brief reference in CLAUDE.md, detail in rule file)
- [ ] No file covers too many distinct topics inline (extract if unwieldy)
- [ ] DO/DON'T code example included
- [ ] Imperative voice throughout

### Next Steps
1. Run `/docsmith:audit` to confirm the new concept scores well
2. If adding a Cursor rule, test the glob pattern: `ls [pattern]`
3. Commit with: `docs: add rule for [concept]`

For Change Mode:

## Update Complete — Concept Changed

**Old:** [OLD_CONCEPT]
**New:** [NEW_CONCEPT]

### Files Modified
| File | Matches Replaced |
|------|-----------------|
| CLAUDE.md | [N] |
| .claude/rules/[topic].md | [N] |
| .cursor/rules/[topic].mdc | [N] |
| AGENTS.md | [N] |

### Total Changes: [N] occurrences across [M] files

### Files with No Matches (unchanged)
[list]

### Post-Change Checks
- [ ] No remaining references to old concept (confirm with Grep)
- [ ] No file grown unwieldy — extract sections if needed
- [ ] No orphaned cross-references

### Next Steps
1. Verify no remaining references: search for '[OLD_CONCEPT]' in AI docs
2. Run `/docsmith:audit` to check for any drift introduced
3. Commit with: `docs: update [OLD_CONCEPT] → [NEW_CONCEPT]`

---

Quick Reference: Decision Rules

Use this when the concept type is ambiguous:

"It keeps making the same mistake"	Rule file
"I do this workflow repeatedly"	Skill (4+ steps) or Command (1-3 steps)
"Should happen automatically"	Hook
"Applies everywhere in the project"	Rule without paths: + CLAUDE.md reference
"Applies only to frontend package"	Rule with paths: packages/frontend/**
"Only for Cursor users"	MDC rule only
"Team-wide, commits to git"	Rule + AGENTS.md + MDC (all tools)
"My personal preference only"	CLAUDE.local.md
"Is already documented elsewhere"	Cross-reference only, no new file
"Doc file is getting too long"	Extract section to rule file, add reference

See also:

• Decision logic: ${CLAUDE_PLUGIN_ROOT}/reference/decision-guide.md
• Authoring quality: ${CLAUDE_PLUGIN_ROOT}/reference/best-practices.md
• Format conversion: ${CLAUDE_PLUGIN_ROOT}/reference/cross-tool-mapping.md