core-fix-skill-docs

# Fix Skill Documentation > **Version:** 2.1.0 | **Last Updated:** 2025-01-27 Check and fix missing reference files in dynamic skills. ## Usage ``` /fix-skill-docs [crate_name] [--check-only] [--remove-invalid] ``` **Arguments:** - `crate_name`: Specific crate to check (optional, defaults to all) - `--check-only`: Only report issues, don't fix - `--remove-invalid`: Remove invalid references instead of creating files ## Execution Mode Detection **CRITICAL: Check if agent infrastructure is available.** This skill can run in two modes: - **Agent Mode**: Uses background agents for documentation fetching - **Inline Mode**: Executes directly using agent-browser CLI or WebFetch --- ## Agent Mode (Plugin Install) **When agent infrastructure is available, use background agents for fetching:** ### Instructions #### 1. Scan Skills Directory ```bash # If crate_name provided skill_dir=~/.claude/skills/{crate_name} # Otherwise scan all for dir in ~/.claude/skills/*/; do # Process each skill done ``` #### 2. Parse SKILL.md for References Extract referenced files from Documentation section: ```markdown ## Documentation - `./references/file1.md` - Description ``` #### 3. Check File Existence ```bash if [ ! -f "{skill_dir}/references/{filename}" ]; then echo "MISSING: {filename}" fi ``` #### 4. Report Status ``` === {crate_name} === SKILL.md: OK references/: - sync.md: OK - runtime.md: MISSING Action needed: 1 file missing ``` #### 5. Fix Missing Files (Agent Mode) Launch background agent to fetch documentation: ``` Task( subagent_type: "general-purpose", run_in_background: true, prompt: "Fetch documentation for {crate_name}/{module} from docs.rs. Use agent-browser CLI to navigate to https://docs.rs/{crate_name}/latest/{crate_name}/{module}/ Extract the main documentation and save to ~/.claude/skills/{crate_name}/references/{module}.md" ) ``` --- ## Inline Mode (Skills-only Install) **When agent infrastructure is NOT available, execute directly:** ### Step 1: Scan Skills Directory ```bash # List all skills ls ~/.claude/skills/ # Or check specific skill ls ~/.claude/skills/{crate_name}/ ``` ### Step 2: Parse SKILL.md for References Read SKILL.md and extract all `./references/*.md` patterns: ```bash # Using Read tool Read("~/.claude/skills/{crate_name}/SKILL.md") # Look for lines like: # - `./references/sync.md` - Sync primitives # - `./references/runtime.md` - Runtime configuration ``` ### Step 3: Check File Existence ```bash # Check each referenced file for ref in references; do if [ ! -f "~/.claude/skills/{crate_name}/references/${ref}.md" ]; then echo "MISSING: ${ref}.md" fi done ``` ### Step 4: Report Status Output format: ``` === {crate_name} === SKILL.md: OK references/: - sync.md: OK - runtime.md: MISSING Action needed: 1 file missing ``` ### Step 5: Fix Missing Files (Inline) For each missing file: **Using agent-browser CLI:** ```bash agent-browser open "https://docs.rs/{crate_name}/latest/{crate_name}/{module}/" agent-browser get text ".docblock" # Save output to ~/.claude/skills/{crate_name}/references/{module}.md agent-browser close ``` **Using WebFetch fallback:** ``` WebFetch("https://docs.rs/{crate_name}/latest/{crate_name}/{module}/", "Extract the main documentation content for this module") ``` Then write the content: ```bash Write("~/.claude/skills/{crate_name}/references/{module}.md", <fetched_content>) ``` ### Step 6: Update SKILL.md (if --remove-invalid) If `--remove-invalid` flag is set and file cannot be fetched: ```bash # Read current SKILL.md Read("~/.claude/skills/{crate_name}/SKILL.md") # Remove the invalid reference line Edit("~/.claude/skills/{crate_name}/SKILL.md", old_string="- `./references/{invalid_file}.md` - Description", new_string="") ``` --- ## Tool Priority 1. **agent-browser CLI** - Primary tool for fetching documentation 2. **WebFetch** - Fallback if agent-browser unavailable 3. **Edit SKILL.md** - For removing invalid references (--remove-invalid only) --- ## Examples ### Check All Skills (--check-only) ```bash /fix-skill-docs --check-only # Output: === tokio === SKILL.md: OK references/: - sync.md: OK - runtime.md: MISSING - task.md: OK === serde === SKILL.md: OK references/: - derive.md: OK Summary: 1 file missing in 1 skill ``` ### Fix Specific Crate ```bash /fix-skill-docs tokio # Fetches missing runtime.md from docs.rs # Reports success ``` ### Remove Invalid References ```bash /fix-skill-docs tokio --remove-invalid # If runtime.md cannot be fetched: # Removes reference from SKILL.md instead ``` --- ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Agent not available | Skills-only install | Use inline mode | | Skills directory empty | No skills installed | Run /sync-crate-skills first | | docs.rs unavailable | Network issue | Retry or use --remove-invalid | | Permission denied | Directory issue | Check ~/.claude/skills/ permissions | | Invalid SKILL.md format | Corrupted skill | Re-generate skill |