docs-management

What this skill does

# 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
>
> ```text
> [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:**

```bash
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

Use the consolidated `docs-ops` skill for common workflows:

- **`/claude-ecosystem:docs-ops scrape`** - Scrape all configured Claude documentation sources, then refresh index and validate
- **`/claude-ecosystem:docs-ops refresh`** - Refresh the local index and metadata without scraping from remote sources
- **`/claude-ecosystem:docs-ops validate`** - Validate the index and references for consistency and drift without scraping
- **`/claude-ecosystem:docs-ops rebuild-index`** - Force rebuild the search index from filesystem
- **`/claude-ecosystem:docs-ops clear-cache`** - Clear the documentation search cache

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

## Quick Reference: Which Command to Use

| I want to... | Command | Example |
|--------------|---------|---------|
| Find docs by keywords | `search` | `search skills progressive` |
| Find docs by natural language | `query` | `query "how to create skills"` |
| Get full document content | `content` | `content code-claude-com-docs-en-skills` |
| Get specific section | `content --section` | `content <doc_id> --section "metadata"` |
| Resolve doc_id to path | `resolve` | `resolve code-claude-com-docs-en-skills` |
| Find related docs | `related` | `related code-claude-com-docs-en-skills` |
| List docs by category | `category` | `category api` |
| List docs by tag | `tag` | `tag skills` |

**Key Workflow:** `search` by keywords → Get `doc_id` from results → `content` by doc_id

**Important distinctions:**

- `search` and `query` accept **flexible keywords** (no full doc_id needed)
- `content`, `resolve`, and `related` require **full doc_id** (e.g., `code-claude-com-docs-en-skills`)

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

```text
# 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