description: Check and fix missing reference files in dynamic skills argument-hint: "[crate_name] [--check-only] [--remove-invalid]"

Fix Skill Documentation

Check dynamic skills for missing reference files and fix them.

Arguments: $ARGUMENTS

crate_name: Specific crate to check (optional, defaults to all crates in ~/.claude/skills/)
--check-only: Only report issues, don't fix
--remove-invalid: Remove references to non-existent files instead of creating them

Instructions

1. Scan Skills Directory

# 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

For each skill, extract referenced files from:

## Documentation

Refer to the local files for detailed documentation:
- `./references/file1.md` - Description
- `./references/file2.md` - Description

Also check "Expected reference files" section if present.

3. Check File Existence

For each referenced file:

if [ ! -f "{skill_dir}/references/{filename}" ]; then
    echo "MISSING: {filename}"
fi

4. Report Status

Output format:

=== {crate_name} ===
SKILL.md: ✅
references/:
  - sync.md: ✅
  - time.md: ✅
  - runtime.md: ❌ MISSING
  - io.md: ❌ MISSING

Action needed: 2 files missing

5. Fix Missing Files

If --check-only: Stop here, only report.

If --remove-invalid: Update SKILL.md to remove invalid references.

Otherwise (default): Generate missing reference files using agent-browser:

# For each missing file
agent-browser "Navigate to docs.rs/{crate_name}/latest/{crate_name}/{module}/
Extract documentation for {topic} including:
- API reference
- Code examples
- Common patterns
Save as markdown."

# Save to references/{filename}

6. Update SKILL.md

After fixing, ensure SKILL.md Documentation section matches actual files:

## Documentation

Refer to the local files for detailed documentation:
- `./references/sync.md` - Synchronization primitives
- `./references/time.md` - Time utilities

Tool Priority

agent-browser CLI - Generate missing documentation
WebFetch - Fallback if agent-browser unavailable
Edit SKILL.md - Remove invalid references (--remove-invalid mode)

Example Usage

# Check all skills
/fix-skill-docs --check-only

# Fix specific crate
/fix-skill-docs tokio

# Check specific crate only
/fix-skill-docs tokio --check-only

# Remove invalid references instead of creating files
/fix-skill-docs tokio --remove-invalid

# Fix all skills
/fix-skill-docs

Output Example

=== Skill Documentation Check ===

tokio:
  SKILL.md: ✅
  references/:
    ✅ sync.md (2.5KB)
    ✅ time.md (2.7KB)
    ❌ runtime.md - MISSING
    ❌ io.md - MISSING
  Status: 2 files missing

tokio-basics:
  SKILL.md: ✅
  references/:
    ✅ runtime-config.md (2.0KB)
    ✅ feature-flags.md (1.5KB)
  Status: Complete ✅

Summary:
- 7 skills checked
- 6 complete
- 1 with missing files

Run `/fix-skill-docs tokio` to fix missing files.