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

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: Registers the plugin and lists available commands. For example, the sales plugin manifest at sales/.claude-plugin/plugin.json defines how Claude recognizes the plugin's capabilities.
• .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.

Skill File Format and Metadata

Each skill is defined in a Markdown file ending with 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. 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 defines the pipeline-review skill that analyzes CRM pipeline health, while the small-business plugin contains small-business/skills/ticket-deflector/SKILL.md for support ticket routing.

Nested Skill Directories

While the core pattern uses one 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 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:

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

/pipeline-review west-coast-team

/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 configuration and returns structured responses according to the skill's defined workflow.

Summary

• Skills are organized within a plugin as individual 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}