Skip to content

docs: restructure README layout #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mgrdich merged 1 commit into from
Feb 18, 2026
Merged

docs: restructure README layout #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 44 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -65,27 +76,19 @@ 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 |
|------------------|--------------------------------------------------------------|------------------------------------------------------------|
| `list_plugins` | List all plugins with optional filters | `type?` (`skill`, `agent`, `prompt`), `tag?` (string) |
| `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):

Expand All @@ -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.

Expand Down Expand Up @@ -142,17 +145,17 @@ 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:

1. Call `list_plugins` or `search_plugins` to discover relevant plugins
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:

Expand All @@ -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.
Expand Down