KillerSkills
Sign in
Documentation

PLUGIN.md Format Reference

The PLUGIN.md format is a standardized specification for defining AI tool plugins. Each plugin file consists of YAML frontmatter followed by markdown content with usage instructions.

Complete Example

---
name: Filesystem Server
description: MCP server providing secure file system access with configurable permissions
platform: mcp
category: development
tags: [filesystem, files, mcp, read, write]
installCommand: npx @modelcontextprotocol/server-filesystem /path/to/allowed/directory
repositoryUrl: https://github.com/modelcontextprotocol/servers
packageIdentifier: "@modelcontextprotocol/server-filesystem"
transport: stdio
license: MIT
version: "1.0.0"
environmentVariables:
  ALLOWED_PATHS: "Comma-separated list of allowed directory paths"
capabilities:
  - read_files
  - write_files
  - list_directory
  - create_directory
---

# Filesystem Server

An MCP server that provides secure, sandboxed file system access to AI assistants.
The server restricts access to explicitly allowed directories, preventing
unauthorized file system operations.

## Installation

Install and run with npx:

```bash
npx @modelcontextprotocol/server-filesystem /path/to/allowed/directory
```

Or install globally:

```bash
npm install -g @modelcontextprotocol/server-filesystem
mcp-server-filesystem /path/to/allowed/directory
```

## Configuration

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents"
      ]
    }
  }
}
```

## Available Tools

- **read_file** — Read contents of a file
- **write_file** — Write content to a file
- **list_directory** — List files in a directory
- **create_directory** — Create a new directory
- **move_file** — Move or rename a file
- **delete_file** — Delete a file (with confirmation)

## Security

The server only allows access to directories explicitly passed as arguments.
All file operations are sandboxed to these paths.

Frontmatter Fields Reference

The YAML frontmatter section contains metadata about the plugin. Fields marked as required must be present for validation to pass.

FieldTypeRequiredDescription
namestringYesShort, descriptive name for the plugin. Must not be empty.
descriptionstringNoBrief description of what the plugin does. Maximum 500 characters.
platformstringYesThe plugin ecosystem. Valid values: claude-code, mcp, gemini-cli, dify, copilot, claude-cowork, other.
categorystringNoPrimary category. Valid values: development, devops, data, design, testing, security, documentation, automation, productivity, communication, other.
tagsstring[]NoList of tags for discovery. Maximum 10 tags.
installCommandstringNoCommand to install and/or run the plugin (e.g., npx @scope/package).
repositoryUrlstringNoURL to the source repository (GitHub, GitLab, etc.).
packageIdentifierstringNoPackage name in the relevant registry (npm, PyPI, crates.io).
transportstringNoCommunication protocol. Common values: stdio, sse, http, websocket.
licensestringNoSPDX license identifier (e.g., MIT, Apache-2.0, GPL-3.0).
versionstringNoVersion string, typically semver (e.g., "1.0.0").
environmentVariablesobjectNoMap of environment variable names to their descriptions. Used to document required configuration.
capabilitiesstring[]NoList of capabilities the plugin provides (e.g., read_files, web_search, execute_code).

Body Content

The markdown body follows the YAML frontmatter (after the closing ---). This section provides detailed documentation for the plugin.

Recommended Sections

  • Overview — what the plugin does and why you'd use it
  • Installation — how to install and configure the plugin
  • Configuration — required environment variables, config files
  • Available Tools — list of tools/capabilities provided
  • Examples — usage examples and common patterns
  • Security — security considerations and permissions

Platform-Specific Notes

MCP Servers

MCP (Model Context Protocol) servers communicate via stdio or SSE. Include:

  • Transport type (stdio is most common)
  • Claude Desktop configuration example
  • List of exposed tools with descriptions

Claude Code Plugins

Claude Code plugins extend the CLI. Document:

  • How to add to Claude Code configuration
  • Any slash commands added
  • Integration with the coding workflow

Validation Rules

Errors (Must Fix)

  • name field is required and must not be empty
  • platform field is required and must be a valid platform identifier

Warnings (Best Practice)

  • Consider adding a description for better discoverability
  • Consider adding an installCommand for easy installation
  • Consider adding capabilities to describe what the plugin can do
  • Consider adding tags to improve search relevance

Next Steps