From 3253851bcb7716aa50245859d4343e3ab75520a7 Mon Sep 17 00:00:00 2001 From: Mgrdich Date: Wed, 18 Feb 2026 11:24:52 -0500 Subject: [PATCH] docs: restructure README to lead with plugins and group repo details Move Current Plugins table to the top, remove folder structure section, and add Current Repo section with writing guides, MCP server info, and contributing guidelines. Co-Authored-By: Claude Opus 4.6 --- README.md | 111 ++++++++++++++++++++++-------------------------------- 1 file changed, 44 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index d605754..6af41df 100644 --- a/README.md +++ b/README.md @@ -13,34 +13,45 @@ A few principles guide the design: - **Plain text wins.** Plugin logic lives in Markdown files. They're easy to read, easy to review, and easy to edit without tooling. - **Discovery is built in.** The repo itself is an MCP server. Other tools and Claude Code instances can search and retrieve plugins programmatically via `list_plugins`, `get_plugin`, and `search_plugins`. -## Repository Structure +## Current Plugins -``` -claude-plugins/ -├── plugins/ # All plugins live here -│ └── {name}/ -│ ├── .claude-plugin/ -│ │ └── plugin.json # Required — manifest -│ ├── agents/{name}.md # Optional — agent workflow prompts -│ ├── skills/{name}/SKILL.md # Optional — slash command prompts -│ ├── prompt.md # Optional — reusable prompt template -│ └── .mcp.json # Optional — bundled MCP server configs -├── src/ # MCP server source (TypeScript) -├── CLAUDE.md # Project instructions for Claude Code -└── package.json -``` +| Plugin | Type | Description | +|-----------------|-------|----------------------------------------------------------| +| `python-expert` | Agent | Python 3.11+, async/await, Pydantic, FastAPI, SQLAlchemy | +| `kotlin-expert` | Agent | Kotlin 2.0+, coroutines, Spring Boot, domain modeling | +| `react-expert` | Agent | React 19+, concurrent rendering, Tailwind, accessibility | + +## Current Repo + +This repository is both a collection of plugins and an MCP server. The server exposes tools that allow any MCP-compatible client — including other Claude Code sessions — to discover, search, and retrieve plugins programmatically. + +### Writing a Good Agent + +Agent prompts in `agents/*.md` define a specialized expert. A strong agent prompt: + +- **States the role clearly** up front — what the agent is an expert in. +- **Encodes real opinions** — prefer pattern X over Y, always use Z. Generic advice is not useful. +- **Includes concrete patterns** — show the actual code structure you want, not just descriptions of it. +- **Covers failure modes** — what to watch out for, common mistakes, performance traps. +- **Stays focused** — one domain of expertise per agent. Compose multiple agents rather than building one that tries to cover everything. -### Plugin Components +### Writing a Good Skill -| Component | Location | Purpose | -|----------------|------------------------------|-------------------------------------------------| -| **Manifest** | `.claude-plugin/plugin.json` | Name, description, version, keywords. Required. | -| **Agent** | `agents/{name}.md` | System prompt for a specialized expert agent. | -| **Skill** | `skills/{name}/SKILL.md` | Prompt template exposed as a `/slash-command`. | -| **Prompt** | `prompt.md` | A reusable prompt template. | -| **MCP Config** | `.mcp.json` | Bundled MCP server configurations. | +Skill prompts in `skills/*/SKILL.md` define a slash command. A strong skill prompt: + +- **Defines the task** — what the skill does when invoked. +- **Specifies inputs** — what arguments or context it needs. +- **Describes the expected output** — format, structure, level of detail. + +### Guidelines + +- Keep plugin names lowercase and hyphenated (`my-plugin`, not `MyPlugin`). +- Use descriptive keywords in the manifest — they power the search tool. +- One concern per plugin. If you're mixing unrelated expertise, split it into separate plugins. +- Write prompts in plain Markdown. No frontmatter, no special syntax. +- Test your plugin by running the MCP server locally and calling `get_plugin` with your plugin name. -## Getting Started +### Getting Started ```bash pnpm install @@ -65,19 +76,11 @@ These slash commands are available when working in this repo with Claude Code: |------------------|--------------------------------------------------------------------------| | `/update-readme` | Regenerate the Current Plugins table in the README from plugin manifests | -## Current Plugins +### MCP Server -| Plugin | Type | Description | -|-----------------|-------|----------------------------------------------------------| -| `python-expert` | Agent | Python 3.11+, async/await, Pydantic, FastAPI, SQLAlchemy | -| `kotlin-expert` | Agent | Kotlin 2.0+, coroutines, Spring Boot, domain modeling | -| `react-expert` | Agent | React 19+, concurrent rendering, Tailwind, accessibility | - -## MCP Server Integration +Any agentic tooling that supports the [Model Context Protocol](https://modelcontextprotocol.io) can connect to this server and programmatically list, search, and retrieve plugins — including their full markdown content. -This repository doubles as an MCP server for plugin discovery. Any agentic tooling that supports the [Model Context Protocol](https://modelcontextprotocol.io) can connect to it and programmatically list, search, and retrieve plugins — including their full markdown content. - -### Available Tools +#### Available Tools | Tool | Description | Parameters | |------------------|--------------------------------------------------------------|------------------------------------------------------------| @@ -85,7 +88,7 @@ This repository doubles as an MCP server for plugin discovery. Any agentic tooli | `get_plugin` | Get a plugin's full details or a single component's markdown | `name` (string), `component?` (`skill`, `agent`, `prompt`) | | `search_plugins` | Full-text search across name, description, and tags | `query` (string), `type?` (`skill`, `agent`, `prompt`) | -### Connect from Claude Code Locally +#### Connect from Claude Code Locally Add the server to your project's `.mcp.json` (or `~/.claude/claude_mcp_settings.json` for global access): @@ -102,7 +105,7 @@ Add the server to your project's `.mcp.json` (or `~/.claude/claude_mcp_settings. Then in any Claude Code session the three tools above become available automatically. -### Connect from other MCP clients +#### Connect from other MCP clients The server supports both **stdio** and **HTTP** transports. @@ -142,7 +145,7 @@ curl -X POST http://localhost:3000/mcp \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' ``` -### Example workflow +#### Example workflow A typical agentic integration pattern: @@ -150,9 +153,9 @@ A typical agentic integration pattern: 2. Call `get_plugin` with `component: "agent"` to retrieve the full markdown prompt 3. Use the returned markdown as a system prompt, agent instruction, or context injection -## Contributing +### Contributing -### Adding a Plugin +#### Adding a Plugin 1. Create the plugin directory and manifest: @@ -175,33 +178,7 @@ mkdir -p plugins/my-plugin/.claude-plugin 4. Run `/update-readme` in Claude Code to regenerate the Current Plugins table in the README. -### Writing a Good Agent - -Agent prompts in `agents/*.md` define a specialized expert. A strong agent prompt: - -- **States the role clearly** up front — what the agent is an expert in. -- **Encodes real opinions** — prefer pattern X over Y, always use Z. Generic advice is not useful. -- **Includes concrete patterns** — show the actual code structure you want, not just descriptions of it. -- **Covers failure modes** — what to watch out for, common mistakes, performance traps. -- **Stays focused** — one domain of expertise per agent. Compose multiple agents rather than building one that tries to cover everything. - -### Writing a Good Skill - -Skill prompts in `skills/*/SKILL.md` define a slash command. A strong skill prompt: - -- **Defines the task** — what the skill does when invoked. -- **Specifies inputs** — what arguments or context it needs. -- **Describes the expected output** — format, structure, level of detail. - -### Guidelines - -- Keep plugin names lowercase and hyphenated (`my-plugin`, not `MyPlugin`). -- Use descriptive keywords in the manifest — they power the search tool. -- One concern per plugin. If you're mixing unrelated expertise, split it into separate plugins. -- Write prompts in plain Markdown. No frontmatter, no special syntax. -- Test your plugin by running the MCP server locally and calling `get_plugin` with your plugin name. - -### Making Changes +#### Making Changes 1. Create a branch from `main`. 2. Add or modify plugins following the structure above.