feat: add native Claude Code Plugin with auto-discovery Skill

.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "claude-code-docs",
+  "owner": {
+    "name": "costiash"
+  },
+  "plugins": [
+    {
+      "name": "claude-docs",
+      "description": "Searchable local mirror of Claude documentation — always fresh, always available",
+      "source": "./plugin"
+    }
+  ]
+}

.gitignore

@@ -20,7 +20,7 @@ wheels/
 venv/
 env/
 ENV/
-
+.env
 # ============================================================================
 # Testing & Coverage
 # ============================================================================
@@ -96,6 +96,10 @@ archive/
 # Plan documents (local development only, contain local paths)
 docs/plans/
 
+# Skill evaluation workspace (development artifacts)
+plugin/skills/claude-docs-workspace/
+plugin/skills/claude-docs/evals/
+
 # ============================================================================
 # Documentation & Tracking Files (DO NOT COMMIT)
 # ============================================================================

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to the enhanced edition of claude-code-docs will be document
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-02-28
+
+### Added
+- **Native Claude Code Plugin**: New `plugin/` directory with full plugin structure
+  - `/docs` slash command — AI-powered documentation search with intent classification
+  - Auto-discovery Skill — Claude proactively searches docs for Claude-related questions without `/docs` prefix
+  - SessionStart hook — automatically clones/updates documentation on each session start
+  - Marketplace registration (`.claude-plugin/marketplace.json`)
+- **Plugin installation method**: Two-command install via `/install-plugin costiash/claude-code-docs` — no Python, jq, or curl required
+- **Scoped search strategy**: Skill instructions route queries to correct doc subcategories based on product context
+- **No-results fallback**: Skill suggests synonyms and `/docs -t` when searches return empty
+- **Expanded category taxonomy**: 11 documentation categories (up from 6) including `agent_sdk`, `agents_and_tools`, `about_claude`, `get_started`, `test_and_evaluate`
+- **Skill quality evaluation suite**: 6 evals with grading, benchmarking, and HTML review viewer (dev artifacts, gitignored)
+
+### Changed
+- **README rewritten**: More inviting, plugin-first installation, comparison table showing value proposition
+- **CLAUDE.md updated**: Added plugin files to structure/key files, fixed category labels table, added all 11 categories
+- **Filename conventions documented**: Corrected URL mapping rules (`claude-code__` → `code.claude.com`, `docs__en__` → `platform.claude.com`)
+
+### Fixed
+- **Broken domain references**: All plugin instruction files now cite correct domains (`platform.claude.com`, `code.claude.com`) — never `docs.anthropic.com` or `docs.claude.com`
+- **CLAUDE.md example URLs**: Fixed `docs.claude.com` → `platform.claude.com` in all code examples
+- **URL mapping in Skill and /docs command**: Filename-to-URL conversion rules corrected for both CLI and platform docs
+
 ## [0.5.1] - 2026-02-27
 
 ### Fixed

CLAUDE.md

@@ -104,9 +104,13 @@ When presenting options to users, always use these user-friendly labels:
 | Internal Category | User-Facing Label |
 |-------------------|-------------------|
 | `claude_code` | Claude Code CLI |
+| `agent_sdk` | Claude Agent SDK |
 | `api_reference` | Claude API |
+| `agents_and_tools` | Agents & Tools |
 | `core_documentation` | Claude Documentation |
-| Agent SDK paths (`/en/docs/agent-sdk/*`) | Claude Agent SDK |
+| `about_claude` | About Claude |
+| `get_started` | Getting Started |
+| `test_and_evaluate` | Testing & Evaluation |
 | `prompt_library` | Prompt Library |
 | `release_notes` | Release Notes |
 | `resources` | Resources |
@@ -156,9 +160,9 @@ When integrating with plugins:
 [Integration details from plugins.md]
 
 Sources:
-• Agent SDK Python Guide: https://docs.claude.com/en/docs/agent-sdk/python
-• Agent SDK Overview: https://docs.claude.com/en/docs/agent-sdk/overview
-• Plugins Integration: https://docs.claude.com/en/docs/agent-sdk/plugins"
+• Agent SDK Python Guide: https://platform.claude.com/en/docs/agent-sdk/python
+• Agent SDK Overview: https://platform.claude.com/en/docs/agent-sdk/overview
+• Plugins Integration: https://platform.claude.com/en/docs/agent-sdk/plugins"
 ```
 
 **Never show**: "Found 3 documents about hooks, which do you want to read?" ❌
@@ -300,9 +304,9 @@ Output:
 [Session persistence from sessions.md]
 
 Sources:
-• Agent SDK Python Guide: https://docs.claude.com/en/docs/agent-sdk/python
-• Agent SDK Overview: https://docs.claude.com/en/docs/agent-sdk/overview
-• Sessions: https://docs.claude.com/en/docs/agent-sdk/sessions"
+• Agent SDK Python Guide: https://platform.claude.com/en/docs/agent-sdk/python
+• Agent SDK Overview: https://platform.claude.com/en/docs/agent-sdk/overview
+• Sessions: https://platform.claude.com/en/docs/agent-sdk/sessions"
 ```
 
 #### Example 2: Ambiguous context (ask, then synthesize)
@@ -435,6 +439,12 @@ See `enhancements/` directory for comprehensive feature documentation and exampl
 │       ├── validation.py           # Path validation
 │       ├── formatting.py           # Output formatting
 │       └── cli.py                  # Main entry point
+├── plugin/                 # Claude Code Plugin (v0.6.0)
+│   ├── .claude-plugin/plugin.json  # Plugin metadata
+│   ├── commands/docs.md    # /docs slash command
+│   ├── skills/claude-docs/ # Auto-discovery Skill + manifest reference
+│   └── hooks/              # SessionStart hook (auto-update docs)
+├── .claude-plugin/marketplace.json # Marketplace registration
 ├── paths_manifest.json     # Active paths manifest (6 categories)
 ├── pyproject.toml          # Python project configuration
 ├── CHANGELOG.md            # Version history
@@ -458,7 +468,15 @@ See `enhancements/` directory for comprehensive feature documentation and exampl
 
 When working on this repository, read these files as needed (not auto-loaded to save context):
 
-### Core Files
+### Plugin Files
+- `plugin/.claude-plugin/plugin.json` - Plugin metadata (version, hooks)
+- `plugin/commands/docs.md` - `/docs` command implementation
+- `plugin/skills/claude-docs/SKILL.md` - Auto-discovery Skill (triggers automatically for Claude topics)
+- `plugin/skills/claude-docs/manifest-reference.md` - Category reference for the Skill
+- `plugin/hooks/hooks.json` + `sync-docs.sh` - SessionStart hook (auto-update docs)
+- `.claude-plugin/marketplace.json` - Marketplace registration
+
+### Core Files (Legacy Script Install)
 - `install.sh` - Installation script
 - `README.md` - User documentation
 - `CONTRIBUTING.md` - Contribution guidelines
@@ -505,8 +523,8 @@ Documentation is discovered from two sitemaps:
 ### Filename Conventions
 
 Files are named based on their source:
-- Platform docs: `en__docs__section__page.md` (double underscore for path separators)
-- Claude Code docs: `docs__en__page.md` (prefixed with `docs__`)
+- Claude Code CLI docs: `claude-code__<page>.md` (e.g., `claude-code__hooks.md`) → `https://code.claude.com/docs/en/<page>`
+- Platform docs: `docs__en__<section>__<page>.md` (e.g., `docs__en__agent-sdk__python.md`) → `https://platform.claude.com/en/docs/<section>/<page>`
 
 ## Working on This Repository
 

README.md

@@ -2,29 +2,54 @@
 
 [![Last Update](https://img.shields.io/github/last-commit/costiash/claude-code-docs/main.svg?label=docs%20updated)](https://github.com/costiash/claude-code-docs/commits/main)
 [![Tests](https://github.com/costiash/claude-code-docs/actions/workflows/test.yml/badge.svg)](https://github.com/costiash/claude-code-docs/actions)
-[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://www.python.org/)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](https://github.com/costiash/claude-code-docs)
 [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
 
-> **Enhanced fork of [ericbuess/claude-code-docs](https://github.com/ericbuess/claude-code-docs)** — adds Python-powered search, validation, and auto-regeneration while maintaining graceful degradation.
+> **Enhanced fork of [ericbuess/claude-code-docs](https://github.com/ericbuess/claude-code-docs)** with native plugin support, auto-discovery Skill, and AI-powered semantic search.
 
-**Fast, searchable access to Claude documentation — locally, always up-to-date.**
+**574+ official Claude docs, always up-to-date, always at your fingertips.** Stop searching the web — ask Claude directly and get accurate answers grounded in official documentation.
 
-## Key Features
+## Why Use This?
 
-- **AI-Powered Search** — Ask questions naturally via `/docs`, Claude routes intelligently
-- **Complete Coverage** — 6 categories of documentation paths tracked and downloaded as markdown
-- **Always Fresh** — Auto-updated every 3 hours via GitHub Actions; run `/docs -t` to pull latest
-- **Graceful Degradation** — Works with or without Python 3.9+
-- **Multi-Language SDK Docs** — Python, TypeScript, Go, Java, Kotlin, Ruby
+Claude knows a lot — but documentation changes fast. API parameters shift, new features land, SDK methods get renamed. This tool gives Claude a local mirror of every official doc page, so answers come from the source, not stale training data.
 
-## Installation
+| Without claude-code-docs | With claude-code-docs |
+|---|---|
+| Claude guesses from training data | Claude reads the latest official docs |
+| Broken or outdated URLs in answers | Correct `platform.claude.com` / `code.claude.com` links |
+| "I think the API works like..." | "According to the documentation..." |
+| You verify answers manually | Answers cite specific doc pages |
+
+## Quick Start — Plugin Install (Recommended)
+
+One command, no dependencies:
+
+```bash
+/install-plugin costiash/claude-code-docs
+```
+
+That's it. On your next session Claude will automatically:
+1. Clone 574+ documentation files to `~/.claude-code-docs/`
+2. Keep them updated every session via `git pull`
+3. Make the `/docs` command available for manual lookups
+4. Activate the **auto-discovery Skill** — Claude reads docs automatically when you ask Claude-related questions
+
+### What the Plugin Gets You
+
+- **`/docs` command** — Look up any topic: `/docs hooks`, `/docs extended thinking`, `/docs Agent SDK sessions`
+- **Auto-discovery Skill** — Claude proactively searches docs when you ask about Claude Code, the API, SDKs, or prompt engineering. No `/docs` prefix needed.
+- **Session-start auto-updates** — Docs stay fresh automatically. No cron jobs, no manual pulls.
+- **Zero dependencies** — No Python, no jq, no curl. Just Claude Code with plugin support.
+
+## Alternative: Script Install
+
+For environments without plugin support, or if you prefer manual control:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/costiash/claude-code-docs/main/install.sh | bash
 ```
 
-This clones the repository to `~/.claude-code-docs`, installs documentation files, and sets up the `/docs` command. Python features activate automatically if Python 3.9+ is available.
+This provides the `/docs` command only (no auto-discovery Skill). Python 3.9+ enables advanced features like full-text content search and path validation.
 
 **CI/CD or non-interactive environments:**
 ```bash
@@ -35,77 +60,87 @@ CLAUDE_DOCS_AUTO_INSTALL=yes curl -fsSL https://raw.githubusercontent.com/costia
 
 ## Usage
 
+### Direct Lookups
+
 ```bash
-/docs hooks              # Read hooks documentation
-/docs mcp                # Read MCP documentation
-/docs -t                 # Check sync status and pull updates
+/docs hooks              # Claude Code hooks
+/docs mcp                # MCP server configuration
+/docs agent sdk python   # Agent SDK Python guide
+/docs -t                 # Check freshness and pull updates
 /docs what's new         # Recent documentation changes
-/docs changelog          # Official Claude Code release notes
 ```
 
 ### Natural Language Queries
 
-The `/docs` command leverages Claude's semantic understanding — ask questions in plain English:
+The `/docs` command understands intent — ask questions in plain English:
 
 ```bash
 /docs what are the best practices for Agent SDK in Python?
 /docs explain the differences between hooks and MCP
-/docs show me everything about memory features
-/docs how do I use extended thinking?
+/docs how do I configure extended thinking for the API?
+/docs show me all prompt library templates
 ```
 
-Claude analyzes your intent, searches relevant documentation, synthesizes answers from multiple sources, and presents results with links.
+Claude finds the right docs, reads them, and synthesizes a clear answer with source links.
 
-### Advanced Commands (Python 3.9+)
+### With the Auto-Discovery Skill (Plugin Only)
 
-```bash
-~/.claude-code-docs/claude-docs-helper.sh --search "keyword"          # Fuzzy path search
-~/.claude-code-docs/claude-docs-helper.sh --search-content "term"     # Full-text content search
-~/.claude-code-docs/claude-docs-helper.sh --validate                  # Check all paths for 404s
-~/.claude-code-docs/claude-docs-helper.sh --status                    # Installation status
-```
+When installed as a plugin, you don't even need `/docs`. Just ask naturally:
 
-## How Updates Work
+> "How do I set up MCP servers in Claude Code?"
 
-1. **Automatic** — GitHub Actions fetches from Anthropic sitemaps every 3 hours
-2. **On-Demand** — `/docs -t` checks for and pulls updates
-3. **Manual** — `cd ~/.claude-code-docs && git pull`
-4. **Safe** — Sync safeguards prevent mass deletion (min discovery threshold, max 10% deletion per sync, min file count)
+Claude recognizes this is a documentation question and automatically reads the relevant docs before answering.
 
-## Documentation Categories
+## Documentation Coverage
 
-Documentation is organized across 6 categories (counts update automatically with each sync):
+574+ documentation files across 11 categories, updated every 3 hours:
 
-- **API Reference** — Complete API docs, Admin API, Agent SDK, multi-language SDK docs
-- **Core Documentation** — Guides, tutorials, prompt engineering, best practices
-- **Claude Code** — CLI-specific docs: hooks, skills, MCP, settings, plugins
+- **API Reference** — Messages API, Admin API, multi-language SDKs (Python, TypeScript, Go, Java, Kotlin, Ruby)
+- **Agent SDK** — Python and TypeScript SDK guides, sessions, hooks, custom tools
+- **Claude Code** — CLI docs: hooks, skills, MCP, plugins, settings, sub-agents
+- **Agents & Tools** — MCP connectors, tool use patterns, agent capabilities
+- **Core Documentation** — Guides, tutorials, prompt engineering, extended thinking
+- **About Claude** — Model capabilities, context windows, pricing
+- **Getting Started** — Quickstart guides
+- **Testing & Evaluation** — Eval frameworks, testing guides
 - **Prompt Library** — Ready-to-use prompt templates
-- **Release Notes** — Version history
+- **Release Notes** — Version history and changelogs
 - **Resources** — Additional resources
 
-Run `~/.claude-code-docs/claude-docs-helper.sh --status` to see current counts.
+## How Updates Work
+
+1. **Automatic (Plugin)** — Docs update via `git pull` at the start of each Claude Code session
+2. **Automatic (CI/CD)** — GitHub Actions fetches from Anthropic sitemaps every 3 hours
+3. **On-Demand** — `/docs -t` checks for and pulls updates
+4. **Safe** — Sync safeguards prevent mass deletion (min 200 paths discovered, max 10% deletion per sync, min 250 files)
 
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
-| `/docs` not found | Check `ls ~/.claude/commands/docs.md`, restart Claude Code |
-| "Installation cancelled" with `curl \| bash` | Use `CLAUDE_DOCS_AUTO_INSTALL=yes` or download first |
+| `/docs` not found | Restart Claude Code; for script install check `ls ~/.claude/commands/docs.md` |
 | Docs seem outdated | `/docs -t` to force update, or `cd ~/.claude-code-docs && git pull` |
-| Check version | `~/.claude-code-docs/claude-docs-helper.sh --version` |
+| Plugin not working | Run `/plugin list` to verify installation |
+| "Installation cancelled" | Use `CLAUDE_DOCS_AUTO_INSTALL=yes` with the curl install |
 
 ## Uninstalling
 
+**Plugin:**
+```bash
+/plugin uninstall claude-docs
+```
+
+**Script install:**
 ```bash
 ~/.claude-code-docs/uninstall.sh
 ```
 
 ## Security
 
 - Input sanitization and path traversal protection
-- Sync safeguards prevent catastrophic documentation loss (min thresholds, max deletion limits, auto-revert)
+- Sync safeguards prevent catastrophic documentation loss
 - All operations limited to documentation directory, HTTPS-only
-- Full test suite with security test coverage
+- Full test suite (303 tests) with security coverage
 
 ## Contributing
 

plugin/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "claude-docs",
+  "version": "0.6.0",
+  "description": "Searchable local mirror of Claude documentation. Provides the /docs command for instant access to API references, guides, and tutorials. Docs auto-update via SessionStart hook.",
+  "author": {
+    "name": "costiash"
+  },
+  "repository": "https://github.com/costiash/claude-code-docs",
+  "license": "MIT",
+  "keywords": ["documentation", "claude", "api", "search", "reference"],
+  "hooks": "./hooks/hooks.json"
+}