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

# 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:

## Documentation

- `./references/file1.md` - Description

#### 3. Check File Existence

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

# 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:

# 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

# 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:

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:

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:

# 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

• agent-browser CLI - Primary tool for fetching documentation

• WebFetch - Fallback if agent-browser unavailable

• Edit SKILL.md - For removing invalid references (--remove-invalid only)

Examples

Check All Skills (--check-only)

/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

/fix-skill-docs tokio

# Fetches missing runtime.md from docs.rs

# Reports success

Remove Invalid References

/fix-skill-docs tokio --remove-invalid

# If runtime.md cannot be fetched:

# Removes reference from SKILL.md instead

Error Handling