# How Skills Are Organized Within the Plugin Structure in Claude Knowledge Work Plugins > Discover how skills are organized in Claude's knowledge work plugins. Each skill uses a SKILL.md file with YAML metadata and Markdown instructions within plugin-specific directories. - Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) - Tags: internals - Published: 2026-05-25 --- **Skills in the knowledge-work-plugins repository are organized as self-contained Markdown files within plugin-specific `skills/` directories, where each skill is defined by a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file containing YAML front-matter for metadata and Markdown content for workflow instructions.** The `anthropics/knowledge-work-plugins` repository implements a file-based architecture that keeps domain-specific capabilities organized and version-controllable. Understanding how different skills are organized within the plugin structure enables developers to extend existing plugins or build custom internal tools without writing executable code. ## Plugin Directory Structure Overview Every plugin follows a consistent four-component layout at the repository root. This separation of concerns ensures that capabilities, configuration, and command definitions remain modular: ``` plugin-name/ ├── .claude-plugin/plugin.json # Manifest that registers the plugin ├── .mcp.json # Connector configuration for external tools ├── commands/ # Explicit slash-commands you invoke └── skills/ # Domain-specific knowledge assets ``` The **[`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)** file registers the plugin with Claude and enumerates its available commands and skills. For example, [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json) defines the sales plugin manifest and its registered capabilities. ## The Skills Directory Structure The `skills/` directory contains the bulk of a plugin’s intelligence. Each skill is a Markdown file ending in [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) that lives within a folder named after the skill identifier. ### Skill Metadata in YAML Front-Matter Every [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file begins with a YAML front-matter block that defines three critical fields: - **`name`** – The identifier used in the slash-command (e.g., `write-query`, `pipeline-review`). - **`description`** – A concise sentence describing when the skill should be invoked. - **`argument-hint`** – A short hint shown to the user for required parameters. Below the front-matter, the file contains Markdown instructions that define the workflow, usage examples, and expected output formats. ## Skill Organization by Functional Domain Skills are grouped by the functional area of the plugin. The repository uses a flat structure inside each `skills/` folder, though sub-folders are permitted for complex domains. ### Sales Plugin Skills Located in `sales/skills/`, this directory contains capabilities for revenue operations. The **`pipeline-review`** skill, defined in [`sales/skills/pipeline-review/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/skills/pipeline-review/SKILL.md), analyzes pipeline health and takes a team identifier as an argument: ```markdown /pipeline-review west-coast-team ``` ### Small Business Plugin Skills The `small-business/skills/` directory contains operational tools for SMB workflows. The **`ticket-deflector`** skill at [`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md) routes support tickets to appropriate teams: ```markdown /ticket-deflector "Customer reports login failure on mobile app" ``` Some plugins use nested sub-folders when domains contain multiple related assets, such as `small-business/skills/tax-season-organizer/`, though each leaf node still contains a single [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file. ### Data Plugin Skills The `data/skills/` directory houses analytics capabilities. The **`write-query`** skill in [`data/skills/write-query/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/write-query/SKILL.md) generates optimized SQL from natural language descriptions: ```markdown /write-query Count of orders by status for the last 30 days ``` This skill connects to databases via the connector defined in the plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration. ## How Claude Resolves and Executes Skills When a user types a slash command, Claude executes a four-step resolution process against the plugin structure: 1. **Parse** the command name (e.g., `write-query`). 2. **Locate** the matching [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file in the plugin's `skills/` directory. 3. **Load** the YAML front-matter to understand arguments and description. 4. **Execute** the workflow defined in the skill file, prompting for missing details if necessary. Because skills are pure Markdown, they can be version-controlled, reviewed via pull requests, and customized for organizational terminology directly in the repository without deploying code. ## Connector Configuration Integration Skills often interact with external tools through the **Model Context Protocol (MCP)**. The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at the plugin root maps skill requirements to external APIs. For instance, [`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json) configures CRM and calendar connectors that the `pipeline-review` skill invokes when analyzing deal flow. ## Summary - **File-based organization**: Each skill is a standalone [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file within a plugin's `skills/` directory. - **Metadata-driven**: YAML front-matter defines the skill name, description, and argument hints that Claude uses for command discovery. - **Domain grouping**: Plugins like `sales`, `small-business`, and `data` organize skills by functional area, with optional sub-folders for complex domains. - **Zero-code customization**: Skills are Markdown-only assets that support version control and organizational customization without code changes. - **Manifest registration**: The [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file registers available skills, while [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configures external tool connectors. ## Frequently Asked Questions ### How does Claude know which skill to execute when I type a slash command? Claude parses the command identifier (the text after the slash) and searches all plugin `skills/` directories for a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file with a matching `name` field in its YAML front-matter. Once found, it loads the metadata and executes the workflow defined in the Markdown content. ### Can I organize skills into subdirectories within the skills folder? Yes. While the standard pattern places [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files immediately inside `skills/`, you can create subdirectories for related capabilities. For example, `small-business/skills/tax-season-organizer/` contains grouped assets while still following the one-[`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md)-per-capability rule. ### What is the difference between the `commands/` folder and the `skills/` folder? The `commands/` directory typically contains explicit slash-command definitions, while the `skills/` directory houses the domain-specific knowledge assets and workflow instructions. The [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files in `skills/` contain the actual implementation logic written in Markdown, whereas `commands/` may define the command structure and routing. ### Do I need to modify the plugin manifest when adding a new skill? Yes. When you add a new [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file to a plugin's `skills/` directory, you should ensure the [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest is updated to register the skill. This manifest tells Claude which capabilities are available in the plugin and maps command names to their respective skill files.