gemini-cli-docs

What this skill does

# Gemini CLI Documentation Skill

## 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 absolute paths** (recommended)
2. **Use separate commands** (never `cd` with `&&`)
3. **Run from repository root** with relative paths

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

## CRITICAL: Large File Handling - MANDATORY SCRIPT USAGE

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

The file exceeds context limits and will cause issues. 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:

- **`/google-ecosystem:docs-ops scrape`** - Scrape Gemini CLI documentation from geminicli.com, then refresh index and validate
- **`/google-ecosystem:docs-ops refresh`** - Refresh the local index and metadata without scraping from remote sources
- **`/google-ecosystem:docs-ops validate`** - Validate the index and references for consistency and drift without scraping
- **`/google-ecosystem:docs-ops rebuild-index`** - Force rebuild the search index
- **`/google-ecosystem:docs-ops clear-cache`** - Clear the documentation search cache

## Overview

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

- **Canonical storage** (encapsulated in skill) - Single source of truth for official docs
- **Subsection extraction** - Token-optimized extracts (60-90% savings)
- **Drift detection** - Hash-based validation against upstream sources
- **Sync workflows** - 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 geminicli.com llms.txt
- **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)

## 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 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py --llms-txt https://geminicli.com/llms.txt`
- **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**

**If you recognize these patterns, STOP and correct immediately.**

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

## Quick Start

### Refresh Index End-to-End (No Scraping)

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

**Use Python 3.13 for validation** - spaCy/Pydantic have compatibility issues with Python 3.14+

```bash
# Use Python 3.13 for full compatibility with spaCy
py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/management/manage_index.py refresh
```

### Scrape All Documentation

Use this when the user explicitly wants to **hit the network and scrape docs**:

```bash
# Scrape from llms.txt
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt

# Refresh index after scraping (use Python 3.13)
py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/management/manage_index.py refresh
```

**With options:**

```bash
# Skip existing files (incremental update)
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt \
  --skip-existing

# Filter to specific section
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt \
  --filter "/docs/"
```

### Find Documentation

```bash
# Resolve doc_id to file path
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py resolve <doc_id>

# Search by keywords (default: 25 results)
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py search checkpointing session

# Search with custom limit
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py --limit 10 search tools

# Natural language search
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py query "how to use checkpointing"

# List by category
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py category docs

# List by tag
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py tag cli
```

**Search Options:**

| Option | Default | Description |
| --- | --- | --- |
| `--limit N` | 25 | Maximum number of results to return |
| `--no-limit` | - | Return all matching results (no limit) |
| `--min-score N` | - | Only return results with relevance score >= N |
| `--fast` | - | Index-only search (skip content grep) |
| `--json` | - | Output results as JSON |
| `--verbose` | - | Show relevance scores |

## Configuration System

The gemini-cli-docs skill uses a unified configuration system with a single source of truth.

**Configuration Files:**

- *