@redpanda-data/docs-extensions-and-macros 4.13.6 → 4.14.0

package/mcp/DEVELOPMENT.adoc

@@ -21,10 +21,6 @@ The MCP server consists of several key components:
 * `generate.js` - Documentation generation commands
 * `cli.js` - Raw CLI command execution
 
-*Prompt system* (`prompts/`):: Pre-defined instructions for specific documentation workflows
-+
-See link:prompts/README.adoc[Prompts documentation]
-
 *Setup automation* (`cli-utils/setup-mcp.js`):: Automated MCP server configuration for Claude Code/Desktop
 
 === How it works
@@ -101,13 +97,13 @@ docs-extensions-and-macros/
 │       ├── antora.js              # Antora structure analysis
 │       ├── cloud-regions.js       # Cloud regions table generation
 │       ├── crd-docs.js            # Kubernetes CRD docs generation
+│       ├── generated-docs-review.js # Generated docs quality review
 │       ├── helm-docs.js           # Helm chart docs generation
 │       ├── index.js               # Main tool orchestrator
 │       ├── job-queue.js           # Background job management
 │       ├── metrics-docs.js        # Metrics docs generation
 │       ├── openapi.js             # OpenAPI bundle generation
 │       ├── property-docs.js       # Property docs generation
-│       ├── review.js              # Documentation quality review
 │       ├── rpcn-docs.js           # Redpanda Connect docs generation
 │       ├── rpk-docs.js            # RPK CLI docs generation
 │       ├── utils.js               # Shared utilities
@@ -246,175 +242,6 @@ Update link:USER_GUIDE.adoc[USER_GUIDE.adoc] to document:
 
 Update link:CLI_INTERFACE.adoc[CLI_INTERFACE.adoc] if you added a new CLI command.
 
-== Adding a new prompt
-
-Prompts provide contextual guidance to Claude when working on specific documentation tasks.
-
-NOTE: This section is for *developers* adding prompts programmatically. *Technical writers* should use link:WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide] which provides step-by-step instructions with no code required.
-
-=== How the prompt system works
-
-The MCP server uses *automatic discovery* of prompts:
-
-. Prompts are Markdown files in `mcp/prompts/` directory
-. Each prompt has YAML frontmatter defining metadata (description, version, arguments)
-. At startup, the server scans the directory and loads all `.md` files
-. Prompts are cached in memory for performance
-. Changes are automatically reloaded in development mode (`MCP_DEV_MODE=true`)
-
-*No code changes needed!* Just drop a `.md` file with valid frontmatter and restart.
-
-=== Step 1: Create the prompt file with frontmatter
-
-Create a new Markdown file in `mcp/prompts/` with YAML frontmatter:
-
-[,bash]
-----
-mcp/prompts/my-docs-guide.md
-----
-
-[,markdown]
-----
----
-description: Guide for working with specific documentation type
-version: 1.0.0
-arguments:
-  - name: content
-    description: The documentation content to process
-    required: true
-argumentFormat: content-append
----
-
-# My Documentation Guide
-
-This guide explains how to work with [specific documentation type].
-
-## Overview
-
-[Explanation of the documentation system]
-
-## Workflow
-
-1. First step
-2. Second step
-3. Third step
-
-## Important rules
-
-- Rule 1
-- Rule 2
-- Rule 3
-
-## Common tasks
-
-### Task 1: Do something
-
-[Detailed instructions]
-
-### Task 2: Do something else
-
-[Detailed instructions]
-
-## Validation
-
-Before committing, check:
-
-- [ ] Checklist item 1
-- [ ] Checklist item 2
-----
-
-*Required frontmatter fields:*
-
-description:: Clear explanation of what the prompt does (min 10 characters)
-version:: Semantic version (for example, "1.0.0")
-arguments:: (Optional) Array of argument definitions
-* `name`: Argument name (lowercase, underscores only)
-* `description`: What this argument is for
-* `required`: Boolean indicating if required
-argumentFormat:: (Optional) How to append arguments:
-* `content-append`: Append content with separator (default)
-* `structured`: Insert arguments as structured sections
-
-*Best practices for prompts:*
-
-* Write for technical writers, not developers
-* Include concrete examples
-* Explain the "why" behind rules
-* Provide validation checklists
-* Use clear, scannable structure
-* Keep version updated when making significant changes
-
-=== Step 2: Validate the prompt
-
-Run validation to check frontmatter and metadata:
-
-[,bash]
-----
-npx doc-tools validate-mcp
-----
-
-This checks:
-
-* YAML frontmatter is valid
-* Required fields are present (description, version)
-* Argument names use only lowercase and underscores
-* Version follows semantic versioning
-* No naming conflicts with existing prompts
-
-=== Step 3: Preview the prompt
-
-Test the prompt before deploying:
-
-[,bash]
-----
-# Preview with content argument
-npx doc-tools preview-prompt my-docs-guide --content "Test content"
-
-# See how it appears to Claude
-----
-
-=== Step 4: Deploy and test
-
-. Restart Claude Code to load the new prompt
-. Test with Claude:
-+
-----
-You: "List available prompts"
-Claude: *shows your new prompt in the list*
-
-You: "Use the my-docs-guide prompt with this content: [...]"
-Claude: *retrieves and applies your prompt*
-----
-
-=== Auto-discovery details
-
-The prompt discovery system (`bin/mcp-tools/prompt-discovery.js`):
-
-. Scans `mcp/prompts/*.md` files
-. Parses YAML frontmatter using `js-yaml`
-. Validates against JSON schema using `ajv`
-. Extracts prompt name from filename (for example, `my-docs-guide.md` → `my-docs-guide`)
-. Caches content and metadata in memory
-. Provides generic handler that works for all prompts
-
-*Development mode:*
-
-Enable file watching to automatically reload changes:
-
-[,bash]
-----
-export MCP_DEV_MODE=true
-# Restart Claude Code
-# Now changes to prompts are automatically reloaded
-----
-
-=== For more information
-
-* link:WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide] - Complete guide for writers adding prompts (no code)
-* link:TEAM_ROLLOUT_GUIDE.adoc#operational-playbook[Operational Playbook] - Managing prompts in production
-* `bin/mcp-tools/prompt-discovery.js` - Auto-discovery implementation
-* `bin/mcp-tools/frontmatter.js` - Frontmatter parsing and validation
-
 == Testing
 
 The MCP server has three types of tests:
@@ -688,7 +515,7 @@ All CLI commands have:
 
 * link:../__tests__/mcp/README.adoc[Test documentation] - How to run and write tests
 * link:CLI_INTERFACE.adoc[CLI interface contract] - CLI interface that the MCP server depends on
-* link:prompts/README.adoc[Prompts documentation] - How the prompt system works
+* link:WRITER_EXTENSION_GUIDE.adoc[Writer extension guide] - When to add MCP tools vs skills
 
 *External documentation*
 

package/mcp/README.adoc

@@ -4,7 +4,9 @@
 
 Documentation for the Redpanda Doc Tools MCP (Model Context Protocol) server.
 
-The MCP server exposes `doc-tools` functionality to Claude Code, allowing technical writers to automate documentation tasks through natural conversation. No CLI knowledge required.
+The MCP server exposes `doc-tools` execution functionality to Claude Code, allowing technical writers to automate documentation generation tasks through natural conversation.
+
+NOTE: Team standards (style guide, content architecture, etc.) have been migrated to the https://github.com/redpanda-data/docs-team-standards[docs-team-standards] Claude Code plugin. This MCP server now focuses on execution tools only.
 
 == Documentation
 
@@ -13,23 +15,10 @@ The MCP server exposes `doc-tools` functionality to Claude Code, allowing techni
 link:USER_GUIDE.adoc[**User guide**]:: Complete guide to using the MCP server with Claude Code
 +
 * Setup and installation
-* Available tools, prompts, and resources
+* Available tools
 * Usage examples and workflows
 * Troubleshooting
 
-link:WRITER_EXTENSION_GUIDE.adoc[**Writer extension guide**]:: How to extend the MCP server (no coding required)
-+
-* Adding new prompts for common tasks
-* Adding new resources (style guides, templates)
-* Validation and preview commands
-* Best practices and examples
-
-link:templates/README.adoc[**Extension templates**]:: Ready-to-use templates for extending the MCP server
-+
-* Templates for review prompts, writing prompts, and resources
-* Step-by-step customization guide
-* No coding required. Just copy and customize
-
 link:COSTS.adoc[**Cost reference**]:: Understanding and optimizing MCP tool costs
 +
 * Cost breakdown by tool ($0.017 - $0.190 per operation)
@@ -42,7 +31,6 @@ link:DEVELOPMENT.adoc[**Development guide**]:: Guide for working on the MCP serv
 +
 * Architecture overview
 * Adding new tools programmatically
-* Auto-discovery system details
 * Testing guidelines
 * Security and best practices
 
@@ -59,20 +47,12 @@ link:../CLI_REFERENCE.adoc[**CLI reference**]:: Complete command reference for `
 * Options and usage examples
 * Auto-generated from CLI help
 
-link:../\__tests__/mcp/README.adoc[**Test documentation**]:: How to run and write MCP tests
+link:../__tests__/mcp/README.adoc[**Test documentation**]:: How to run and write MCP tests
 +
 * Test types (integration, contract, unit)
 * Running tests
 * Understanding failures
 
-=== Advanced
-
-link:prompts/README.adoc[**Prompts documentation**]:: Guide to the MCP prompt system
-+
-* What prompts are and how they work
-* Available prompts
-* Adding new prompts
-
 == Quickstart
 
 === Install and configure
@@ -109,47 +89,24 @@ Claude: *uses generate_property_docs tool*
 * **Metrics docs**: Generate metrics reference documentation
 * **RPK docs**: Generate RPK CLI documentation
 * **Connector docs**: Generate Redpanda Connect connector documentation
-* **Antora structure**: Analyze documentation repository structure
-
-=== AI consistency prompts
-
-Pre-configured instructions that help Claude follow your team standards:
-
-**Review prompts:**
+* **Helm docs**: Generate Helm chart documentation
+* **CRD docs**: Generate Kubernetes CRD documentation
+* **OpenAPI bundling**: Bundle OpenAPI fragments
+* **Cloud regions**: Generate cloud regions documentation
 
-* **review-for-style**: Review content for style guide compliance
-* **check-terminology**: Validate terminology against approved terms
-* **improve-clarity**: Refactor content for better readability
+=== Utility tools
 
-**Content creation:**
-
-* **write-new-guide**: Generate new guides following team standards
-
-**Workflow guides:**
-
-* **property-docs-guide**: Workflow for updating property documentation
-* **rpcn-connector-docs-guide**: Workflow for updating connector documentation
+* **Antora structure**: Analyze documentation repository structure
+* **Review generated docs**: Quality check generated documentation
+* **Job management**: Background job status and listing
 
 === Resources
 
-Reference materials that Claude can read:
-
-* **redpanda://style-guide**: Complete team style guide with formatting rules
-
-=== CLI validation commands
+The only resource provided by this MCP server is:
 
-For writers extending the MCP server:
+* **redpanda://personas**: Target audience personas (loaded from current repo's `docs-data/personas.yaml`)
 
-* **npx doc-tools validate-mcp**: Validate prompts and resources configuration
-* **npx doc-tools preview-prompt**: Preview prompts with test arguments
-* **npx doc-tools mcp-version**: Show versions and usage statistics
-
-=== Automation
-
-* **setup-mcp**: Automated MCP server configuration for Claude Code/Desktop
-* **Auto-discovery**: Prompts automatically loaded from `mcp/prompts/` directory
-* **Context detection**: Automatic repository and Antora structure detection
-* **Usage telemetry**: Track prompt/resource/tool usage for adoption metrics
+All other resources (style guide, content architecture, etc.) have been migrated to the https://github.com/redpanda-data/docs-team-standards[docs-team-standards] Claude Code plugin.
 
 == Architecture
 
@@ -157,16 +114,25 @@ The MCP server consists of:
 
 * **Server** (`bin/doc-tools-mcp.js`): Main MCP protocol handler
 * **Tool modules** (`bin/mcp-tools/`): Individual tool implementations
-* **Prompts** (`mcp/prompts/`): Contextual documentation guides
 * **Tests** (`__tests__/mcp/`): Integration, contract, and unit tests
 
+== Migration notice
+
+As of January 2025, the following have been migrated to the https://github.com/redpanda-data/docs-team-standards[docs-team-standards] Claude Code plugin:
+
+* **Prompts**: All MCP prompts are now Claude Code skills and agents
+* **Resources**: Style guide, content architecture, learning objectives, etc. are now Claude Code skills
+
+The MCP server now focuses exclusively on execution tools that require CLI or web access.
+
 == Support
 
 * link:USER_GUIDE.adoc#troubleshooting[Troubleshooting guide]
-* link:../\__tests__/mcp/README.adoc#understanding-test-failures[Test failures]
+* link:../__tests__/mcp/README.adoc#understanding-test-failures[Test failures]
 * https://github.com/redpanda-data/docs-extensions-and-macros/issues[Report issues]
 
 == External resources
 
 * https://modelcontextprotocol.io/[MCP Protocol Specification]
 * https://docs.anthropic.com/claude[Claude Code Documentation]
+* https://github.com/redpanda-data/docs-team-standards[docs-team-standards Plugin]