Docs Management

Claude Docs Management

🚨🚨🚨 MANDATORY: Hybrid Parallel Pattern 🚨🚨🚨

STOP - Before using this skill for ANY Claude Code documentation query:

IF YOU ARE THE MAIN AGENT, you MUST invoke BOTH sources in the same message:

1. This skill (docs-management) - local cache, token-efficient
2. claude-code-guide subagent - live web search

[Skill tool: docs-management]
"Find documentation about {topic}"

[Task tool: claude-code-guide] (SAME MESSAGE - USE THIS EXACT PROMPT)
"First WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md to find
relevant doc pages about {topic}. Then WebFetch those specific pages. Use WebSearch
only if needed for additional context. Do NOT use Skill tool (not available).
Return key findings with source URLs."

⚠️ CRITICAL: claude-code-guide does NOT have Skill tool access. Always prompt it to use WebSearch/WebFetch explicitly. If you see "No such tool: Skill" error, you prompted it wrong.

This is AUTOMATIC. Do NOT wait for user to ask for it.

IF YOU ARE A SUBAGENT: Note in your response that main agent should also query claude-code-guide.

🚨 CRITICAL: Path Doubling Prevention - MANDATORY

ABSOLUTE PROHIBITION: NEVER use cd with && in PowerShell when running scripts from this skill.

The Problem: If your current working directory is already inside the skill directory, using relative paths causes PowerShell to resolve paths relative to the current directory instead of the repository root, resulting in path doubling.

REQUIRED Solutions (choose one):

1. ✅ ALWAYS use helper scripts (recommended - they handle path resolution automatically)
2. ✅ Use absolute path resolution (if not using helper script)
3. ✅ Use separate commands (never cd with &&)

NEVER DO THIS:

• ❌ Chain cd with &&: cd <relative-path> && python <script> causes path doubling
• ❌ Assume current directory
• ❌ Use relative paths when current dir is inside skill directory

For all scripts: Always run from repository root using relative paths, OR use helper scripts that handle path resolution automatically.

🚨 CRITICAL: Large File Handling - MANDATORY SCRIPT USAGE

⚠️ ABSOLUTE PROHIBITION: NEVER use read_file tool on the index.yaml file

The file exceeds 25,000 tokens and will ALWAYS fail. You MUST use scripts.

✅ REQUIRED: ALWAYS use manage_index.py scripts for ANY index.yaml access:

python scripts/management/manage_index.py count
python scripts/management/manage_index.py list
python scripts/management/manage_index.py get <doc_id>
python scripts/management/manage_index.py verify

All scripts automatically handle large files via index_manager.py.

Available Slash Commands

This skill provides three slash commands for common workflows:

• /claude-ecosystem:scrape-docs - Scrape all configured Claude documentation sources, then refresh index and validate
• /claude-ecosystem:refresh-docs - Refresh the local index and metadata without scraping from remote sources
• /claude-ecosystem:validate-docs - Validate the index and references for consistency and drift without scraping

Overview

This skill provides automation tooling for documentation management. It manages:

• Canonical storage (encapsulated in skill) - Single source of truth for official docs
• Subsection extraction - Token-optimized extracts for skills (60-90% savings)
• Drift detection - Hash-based validation against upstream sources
• Sync workflows - Quarterly maintenance automation
• Documentation discovery - Keyword-based search and doc_id resolution
• Index management - Metadata, keywords, tags, aliases for resilient references

Core value: Prevents link rot, enables offline access, optimizes token costs, automates maintenance, and provides resilient doc_id-based references.

When to Use This Skill

This skill should be used when:

• Scraping documentation - Fetching docs from sitemaps or docs maps
• Finding documentation - Searching for docs by keywords, category, or natural language
• Resolving doc references - Converting doc_id to file paths
• Managing index metadata - Adding keywords, tags, aliases, updating metadata
• Rebuilding index - Regenerating index from filesystem (handles renames/moves)

Hybrid Parallel Documentation Strategy

CRITICAL: This section is the authoritative source for Claude Code documentation access patterns.

Architecture Constraint

Skills cannot spawn subagents. Only the main conversation thread can use the Task tool.

This means:

• When main agent loads this skill → Main agent must also invoke claude-code-guide in parallel
• When subagent loads this skill → Subagent should note in response that main agent should invoke claude-code-guide for live coverage
• When command invokes this skill → Same as main agent (commands run in main context)

Caller-Aware Guidance

If you are the main agent:

• You MUST invoke both this skill AND claude-code-guide subagent in the SAME message
• This is the only way to get comprehensive Claude Code documentation coverage

If you are a subagent:

• You CANNOT invoke claude-code-guide yourself (architectural constraint)
• Include in your response: "For comprehensive coverage, main agent should also query claude-code-guide subagent"
• Proceed with local cache results

Always-Parallel Pattern (Main Agent Only)

⚠️ MANDATORY DEFAULT BEHAVIOR - NOT OPTIONAL:

When ANY Claude Code documentation query is detected, the main agent MUST automatically:

1. Invoke docs-management skill (local cache)
2. Spawn claude-code-guide subagent (live web) in the same message

This is automatic. The user does NOT need to ask for it.

Detection Triggers

Use both sources automatically when user asks about:

• Claude Code features (hooks, skills, memory, MCP, plugins, settings, etc.)
• How to do something in Claude Code
• Claude Code configuration or troubleshooting
• Any topic in the Claude Code documentation

Same-Message Parallel Invocation

# Main agent sends BOTH in a single message (AUTOMATIC):

[Skill tool: docs-management]
"Find documentation about {topic}"

[Task tool: claude-code-guide] (same message = parallel execution)
"First WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md to find
relevant doc pages about {topic}. Then WebFetch those specific pages. Use WebSearch
only if needed for additional context. Do NOT use Skill tool (not available).
Return key findings with source URLs."

IMPORTANT: claude-code-guide is a built-in subagent with tools: Glob, Grep, Read, WebFetch, WebSearch. It does NOT have the Skill tool - it's designed for web search, not local skill invocation. Always prompt it to use WebSearch/WebFetch explicitly.

Synthesis Step

After both complete:

• Combine results from both sources
• Local cache provides category context and token efficiency
• Live search provides currency and gap-filling
• Note any discrepancies between sources

Two Documentation Sources

Fallback Behavior

• Plugin not installed: Use claude-code-guide only
• Live search unavailable: This skill provides complete local cache
• Both sources disagree: Flag discrepancy, prefer official docs, investigate

Automatic Behavior Summary

There is no manual trigger. This is default behavior for Claude Code documentation queries.

Three-Source Troubleshooting Pattern

When troubleshooting errors, bugs, or unexpected behavior, use three sources in parallel:

Troubleshooting triggers (automatically detected by hook):

• "error", "bug", "broken", "not working", "fails", "crash"
• "debug", "troubleshoot", "workaround", "issue", "problem"
• "doesn't work", "won't work", "can't", "isn't firing"

Example prompt for claude-code-issue-researcher:

Search GitHub issues in anthropics/claude-code for: [ERROR/PROBLEM DESCRIPTION].
Check both open and closed issues. Report issue numbers, status, and any workarounds.

Correct Subagent Pattern

When spawning docs-researcher (or any subagent that uses this skill), the main agent should ALSO spawn claude-code-guide in the same message for comprehensive coverage:

# Main agent spawns BOTH in a single message:

[Task tool: docs-researcher subagent]
"Research Claude Code memory/CLAUDE.md files"

[Task tool: claude-code-guide subagent] (same message = parallel)
"Use WebSearch to find current Claude Code documentation about memory and
CLAUDE.md files on code.claude.com. Return key findings with URLs."

# After both complete, synthesize results

Why both? The docs-researcher uses local cache (fast, token-efficient), while claude-code-guide searches live web (always current). Together they provide comprehensive coverage.

Hierarchical Categories (from docs_map.md)

The index includes category hierarchy from the official Claude Code docs map:

Categories are stored in doc_map_category field. Query by category:

resolver.get_by_category("Build with Claude Code")  # Returns all docs in category
resolver.list_categories()  # Returns all categories with counts

Category Enrichment

After scraping, update categories from the official docs map:

python scripts/core/enrich_categories.py           # Update categories
python scripts/core/enrich_categories.py --dry-run # Preview changes

Workflow Execution Pattern

CRITICAL: This section defines HOW to execute operations in this skill.

Delegation Strategy

Default approach: Delegate to Task agent

For ALL scraping, validation, and index operations, delegate execution to a general-purpose Task agent.

How to invoke:

Use the Task tool with:

• subagent_type: "general-purpose"
• description: Short 3-5 word description
• prompt: Full task description with execution instructions

Execution Pattern

Scripts run in FOREGROUND by default. Do NOT background them.

When Task agents execute scripts:

• ✅ Run directly: python .claude/skills/docs-management/scripts/core/scrape_all_sources.py --parallel --skip-existing
• ✅ Streaming logs: Scripts emit progress naturally via stdout
• ✅ Wait for completion: Scripts exit when done with exit code
• ❌ NEVER use run_in_background=true: Scripts are designed for foreground execution
• ❌ NEVER poll output: Streaming logs appear automatically, no BashOutput polling needed
• ❌ NEVER use background jobs: No &, no nohup, no background process management

Anti-Pattern Detection

Red flags indicating incorrect execution:

🚩 Using run_in_background=true in Bash tool 🚩 Repeated BashOutput calls in a loop 🚩 Checking process status with ps or pgrep 🚩 Manual polling of script output 🚩 Background job management (&, nohup, jobs) 🚩 Using BashOutput AFTER Task agent completes ← CRITICAL RED FLAG

If you recognize these patterns, STOP and correct immediately.

After Task Agent Completes

CRITICAL: When the Task agent reports "Done", READ its report and summarize to the user. DO NOT use BashOutput.

Correct workflow:

1. Task agent reports "Done (X tool uses · Y tokens · Z time)"
2. ✅ READ the agent's message containing its final report
3. ✅ SUMMARIZE the agent's findings to the user
4. ❌ NEVER use BashOutput to "check the real results"
5. ❌ NEVER poll or verify what the agent already reported

Error and Warning Reporting

CRITICAL: Report ALL errors, warnings, and issues - never suppress or ignore them.

When executing scripts via Task agents:

• ✅ Report script errors: Exit codes, exceptions, error messages
• ✅ Report warnings: Deprecation warnings, import issues, configuration problems
• ✅ Report unexpected output: 404s, timeouts, validation failures
• ✅ Include context: What was being executed when the error occurred

Red flags that indicate issues:

🚩 Non-zero exit code 🚩 Lines containing "ERROR", "FAILED", "Exception", "Traceback" 🚩 "WARNING" or "WARN" messages 🚩 "404 Not Found", "500 Internal Server Error"

Domain-Specific Reporting for Scraping

CRITICAL: When reporting scraping results, distinguish behavior by domain.

Domain-Specific .md URL Behavior:

1. docs.claude.com and code.claude.com: These domains serve .md URLs successfully
2. anthropic.com: These domains do NOT serve .md URLs (404 expected, configured with try_markdown: false)

Accurate Reporting:

✅ Good (Domain-Specific): "docs.claude.com: 97 URLs using direct .md (97 skipped/unchanged). anthropic.com: 164 URLs using HTML conversion (158 skipped/unchanged)."

❌ Bad (Misleading): "All .md URL attempts returned 404 (expected - these are HTML pages)" ← This is misleading because Claude domains successfully use .md URLs

Quick Start

Refresh Index End-to-End (No Scraping)

Use this when you want to rebuild and validate the local index/metadata without scraping:

⚠️ IMPORTANT: Use Python 3.13 for validation - spaCy/Pydantic have compatibility issues with Python 3.14+

# Use Python 3.13 for full compatibility with spaCy
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py

Optional flags:

# Check for missing files before rebuilding
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-missing-files

# Detect drift (404s, missing files) after rebuilding
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-drift

# Detect and automatically cleanup drift
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-drift --cleanup-drift

This script runs the full pipeline:

• ✅ Checks dependencies
• ✅ (Optional) Checks for missing files
• ✅ Rebuilds the index from the filesystem
• ✅ Extracts keywords & metadata for all documents
• ✅ Validates metadata coverage
• ✅ Generates a summary report
• ✅ (Optional) Detects and cleans up drift

Expected runtime: ~20-30 seconds for ~500 documents