# How Skills Are Organized Within a Plugin: File Structure and Discovery in Knowledge-Work-Plugins

> Discover how skills are organized in knowledge-work-plugins. Learn about self-contained Markdown files, YAML front-matter, and registration via plugin manifests.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: internals
- Published: 2026-06-01

---

**Skills in the knowledge-work-plugins repository are organized as self-contained Markdown files with YAML front-matter, stored in a `skills/` directory within each plugin folder and registered via the plugin manifest.**

The *anthropics/knowledge-work-plugins* repository provides a modular architecture for extending Claude with domain-specific capabilities. Understanding how skills are organized within a plugin is essential for customizing existing functionality or building new extensions. Each plugin follows a consistent file-based layout that separates configuration, commands, and knowledge assets into distinct components.

## The Plugin Directory Structure

Every plugin in the repository follows a predictable top-level pattern:

```

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 **skills** directory contains the core intelligence of the plugin. Unlike traditional code-based extensions, these skills are pure Markdown files that can be version-controlled and edited without touching application code.

### Key Configuration Files

- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)**: Registers the plugin and lists available commands. For example, the sales plugin manifest at [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json) defines how Claude recognizes the plugin's capabilities.
- **[`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)**: Maps external tools to the Model Context Protocol, enabling skills to interact with CRMs, databases, or calendars as implemented in [`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json).

## Skill File Format and Metadata

Each skill is defined in a Markdown file ending with [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) and begins with a YAML front-matter block that specifies three critical fields:

- `name`: The identifier used in slash-commands (e.g., `write-query`, `pipeline-review`)
- `description`: A concise explanation of when the skill should be invoked
- `argument-hint`: Guidance shown to users for required parameters

### Real-World Example: The Write-Query Skill

The data plugin's `write-query` skill demonstrates this structure in [`data/skills/write-query/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/write-query/SKILL.md). This skill writes optimized SQL from natural-language prompts and includes usage instructions, workflow steps, and example invocations directly in the Markdown body.

## Functional Grouping of Skills

Skills are organized by the plugin's domain area. The repository uses a flat structure inside each `skills/` folder, though sub-folders are permitted for complex domains.

| Plugin | Skills Directory | Example Skill |
|--------|------------------|---------------|
| **sales** | `sales/skills/` | `pipeline-review` – analyzes pipeline health |
| **small-business** | `small-business/skills/` | `ticket-deflector` – routes support tickets |
| **data** | `data/skills/` | `write-query` – generates SQL from descriptions |
| **productivity** | `productivity/skills/` | `task-management` – organizes personal tasks |
| **partner-built/zoom-plugin** | `partner-built/zoom-plugin/skills/` | `zoom-mcp` – integrates Zoom meetings |

For instance, the sales plugin at [`sales/skills/pipeline-review/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/skills/pipeline-review/SKILL.md) defines the **pipeline-review** skill that analyzes CRM pipeline health, while the small-business plugin contains [`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md) for support ticket routing.

### Nested Skill Directories

While the core pattern uses one [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) per capability, some plugins organize related skills into sub-folders. The small-business plugin uses `small-business/skills/tax-season-organizer/` to group related tax capabilities, maintaining the same single-file pattern within the sub-directory.

## How Claude Resolves Skills at Runtime

When a user types a slash-command such as `/write-query`, Claude executes a four-step resolution process:

1. **Parse**: Extracts the command name (`write-query`) from the user input.
2. **Locate**: Searches for a matching [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file across all plugin `skills/` directories.
3. **Load**: Reads the YAML front-matter to understand arguments, description, and constraints.
4. **Execute**: Runs the workflow defined in the skill body, prompting for missing details when necessary.

Because skills are pure Markdown according to the knowledge-work-plugins source code, they integrate seamlessly with version control systems and can be customized for organizational terminology without code deployment.

## Invoking Skills: Practical Examples

Skills are triggered via slash-commands in a Claude session. The following commands demonstrate typical invocations:

```markdown
/write-query Count of orders by status for the last 30 days

```

```markdown
/pipeline-review west-coast-team

```

```markdown
/ticket-deflector "Customer reports login failure on mobile app"

```

Each command triggers the corresponding skill file, which pulls in relevant connectors via the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration and returns structured responses according to the skill's defined workflow.

## Summary

- Skills are organized within a plugin as individual [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files located in the `skills/` directory.
- Each skill uses YAML front-matter to define metadata including `name`, `description`, and `argument-hint`.
- The structure is flat by design, though sub-folders are supported for grouping related capabilities.
- Skills are registered through the [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest and discovered at runtime by matching command names to file paths.
- This Markdown-based architecture allows for version control, pull request reviews, and organizational customization without writing code.

## Frequently Asked Questions

### What is the file naming convention for skills?

Every skill file must end with [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) to be recognized by the plugin system. The prefix determines the slash-command name used to invoke the capability, and the file must reside within a `skills/` directory inside the plugin folder.

### Can skills be organized in subdirectories?

Yes. While the standard pattern places [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files directly in `skills/`, you can create sub-folders for functional grouping. For example, `small-business/skills/tax-season-organizer/` organizes tax-related capabilities separately from general business skills while maintaining the same single-file pattern.

### How does Claude know which skill to execute?

Claude matches the slash-command name against the `name` field in each skill's YAML front-matter. Once found, it loads the corresponding [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file from the plugin's `skills/` directory and executes the workflow defined in the Markdown body.

### Do skills require programming knowledge to modify?

No. Skills are written in Markdown with YAML front-matter, making them accessible to technical writers and domain experts. You can edit instructions, examples, and workflows directly in the text files without compiling code or deploying applications.