# What Are Markdown Skill Plugins? Architecture and Examples from Claude Plugins Community > Discover Markdown skill plugins self-documenting capability definitions that instruct Claude agents on CLI commands and API workflows without code modification. Explore examples from the Claude Plugins Community. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: architecture - Published: 2026-08-26 --- **Markdown skill plugins are self-documenting capability definitions that use YAML-fronted markdown files to instruct Claude agents how to execute CLI commands and API workflows without modifying executable code.** The `anthropics/claude-plugins-community` repository implements this pattern through standalone [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files that serve as both documentation and runtime configuration. Each file declares its name and description via YAML front-matter while containing the full operational knowledge—usage guidelines, cardinal rules, and command snippets—that Claude references when fulfilling user requests. ## Architecture of Markdown Skill Plugins The repository organizes capabilities through a hierarchical directory structure that separates manifests from skill definitions. ### Plugin Root and Manifest Layer Every plugin begins in the `.claude-plugin/` directory containing [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). This manifest enumerates the plugin's name, version, and entry-point metadata, enabling the Claude runtime to discover available capabilities at initialization. ### Skill Folder Structure Individual capabilities reside in `skills//` directories, each containing a single [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. The markdown parser extracts the YAML front-matter to identify the skill's **name** and **description**, then treats the remaining content as the operational knowledge base. This design allows complex CLI integrations to be defined entirely through documentation. ### Reference Materials and Pipelines Optional subdirectories enhance maintainability: - **`references/`** – Reusable markdown files containing model-specific guidance or best practices that main skill files can link to - **`pipelines/`** – Multi-step workflow documentation - **`models/`** – Command-line flag specifications for specific AI models ## Runtime Execution Flow When Claude receives a request matching a skill's description, the runtime loads the corresponding [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) from the plugin directory. The parser extracts relevant sections—such as cardinal rules or command templates—and presents them to the user or executes the described CLI commands directly. This architecture decouples capability definition from implementation. Because the documentation is pure markdown, updating the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file immediately exposes new functionality without recompiling or redeploying executable code. ## Real-World Implementation Examples The following examples demonstrate how skills translate markdown documentation into executable workflows. ### QuickDesign Video Generation Located at [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), this skill wraps the `quickdesign` CLI for generating talking-avatar videos. The documentation defines cardinal rules and links to model-specific references like [`references/no-music-no-subtitles.md`](https://github.com/anthropics/claude-plugins-community/blob/main/references/no-music-no-subtitles.md). ```bash # Generate a product showcase video using the QuickDesign skill quickdesign video generate \ --provider seedance \ --reference-image avatar.jpg \ --reference-image product.jpg \ --aspect-ratio 9:16 --duration 12 --resolution 1080p \ -p '@Image1 holds @Image2. She says: "Check out our new product!" No music score. No subtitles.' \ -o output.mp4 --wait ``` ### TestDino Testing Sessions The [`testdino/skills/testdino-sessions/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/skills/testdino-sessions/SKILL.md) file defines a concise API integration for exploratory testing services. It instructs Claude to invoke specific endpoints with structured parameters. ```bash # List open testing sessions via the TestDino skill claude plugin invoke testdino-sessions list_sessions \ --projectId my-project \ --state open ``` ### Tres Finance Wallet Uploads Found in [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md), this finance-oriented skill guides the agent through data validation and upload workflows. ```bash # Upload wallet balance data using the Tres Finance skill quickdesign finance wallet upload \ --file balances.xlsx \ --wallet-id 12345 ``` ## Critical File Reference Guide Understanding the repository structure requires familiarity with these specific paths: - **[`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md)** – Canonical example wrapping a CLI tool with cardinal rules and reference links - **[`testdino/skills/testdino-sessions/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/skills/testdino-sessions/SKILL.md)** – Demonstrates external API interaction patterns - **[`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md)** – Shows data validation and upload guidance - **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** – Runtime manifest enumerating all available skills - **[`quickdesign/skills/quickdesign/references/no-music-no-subtitles.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/references/no-music-no-subtitles.md)** – Reusable reference snippet illustrating best practices ## Summary - **Markdown skill plugins** are documentation-first capability definitions using [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files with YAML front-matter - The architecture separates the **plugin manifest** ([`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)) from **skill definitions** (`skills//SKILL.md`) - Runtime parsing enables immediate updates without code redeployment, as Claude re-reads the markdown files for each relevant request - Reference materials in `references/` directories provide reusable guidance across multiple skills - Real-world implementations include CLI wrappers (QuickDesign), API integrations (TestDino), and data processing workflows (Tres Finance) ## Frequently Asked Questions ### What file format do Markdown skill plugins use? Each skill is a markdown file named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) containing a YAML front-matter block that declares the **name** and **description** fields, followed by standard markdown documentation that serves as the operational knowledge base. ### How does Claude discover available skills? The runtime loads the [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifest to enumerate installed plugins, then scans each plugin's `skills/` directory for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files. The YAML front-matter in each file registers the skill's capabilities with the agent. ### Can skills be modified without changing executable code? Yes. Because skills are pure markdown documentation, editing a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file immediately updates Claude's behavior. The runtime re-parses the file at request time, eliminating the need for code compilation or binary redeployment when updating command templates or guidelines. ### What is the purpose of the references/ subdirectory? The `references/` folder contains reusable markdown snippets—such as model-specific command flags or best-practice examples—that multiple [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files can link to, promoting consistency and reducing duplication across complex plugins like the QuickDesign implementation.