Skills-Based Architecture for Claude Plugins: How Declarative Markdown Powers AI Workflows

Claude plugins use a skills-first architecture where self-contained markdown files define capabilities that Claude Code discovers at runtime and exposes as slash commands.

The anthropics/claude-plugins-community repository demonstrates this architecture in practice. Instead of monolithic APIs, each plugin consists of declarative skill documents that Claude reads to understand when and how to invoke specific functionality. This design treats capabilities as documentation-first, enabling the model to reason about tool selection through natural language guidance embedded in the skills themselves.

Core Components of the Skills-Based Architecture

The architecture rests on three primary file types that work together to register, describe, and validate plugin capabilities.

Skill Definitions (SKILL.md Files)

At the heart of the system lies the SKILL.md file—a markdown document with YAML front-matter that declares a single capability. Located in skills/<skill-name>/SKILL.md within each plugin directory, these files contain:

• YAML header: Defines name and description fields that become the slash command identifier (e.g., /quickdesign)
• Documentation body: Contains when-to-invoke guidance, cardinal rules, and decision trees that drive model behavior
• Runtime instructions: Explains parameter usage and workflow logic without requiring procedural code

For example, in quickdesign/skills/quickdesign/SKILL.md, the front-matter registers the command while the markdown body teaches Claude how to generate videos using specific syntax like @Image labels and aspect ratio flags.

Plugin Manifests (plugin.json)

Each plugin directory includes a .claude-plugin/plugin.json file that serves as the package manifest. This JSON file registers the plugin name, description, and optional MCP (Model Context Protocol) server configurations. The manifest points to external resources and defines the plugin's entry point, allowing the CLI to locate skills during installation.

Marketplace Index (marketplace.json)

The repository root contains .claude-plugin/marketplace.json, a generated registry of all community plugins. This file aggregates every plugin.json across the repository and enables the claude plugin install command to resolve plugin locations. When users run installation commands, Claude Code reads this index to fetch the correct skill files and copy them to the local environment.

How Skill Discovery and Runtime Execution Work

The skills-based architecture separates declaration from execution through a distinct lifecycle that runs from installation to invocation.

Discovery at Startup

When Claude Code initializes, it scans the ~/.claude/skills/ directory for all SKILL.md files. Each file's YAML header is parsed to register a slash command (e.g., /tres-onboarding). The system builds a skill graph that resolves dependencies between skills, creating a map of available capabilities without loading procedural code.

Execution Flow

When the model determines a skill is appropriate for a user request, it emits the corresponding slash command. Claude Code maps this command to the skill's SKILL.md file and follows the documented cardinal rules and decision trees to execute the workflow. For example, invoking /quickdesign triggers the logic defined in quickdesign/skills/quickdesign/SKILL.md, including parameter validation and output formatting rules.

Runtime Validation

The repository includes .github/workflows/validate-plugins.yml, which runs claude plugin validate against every manifest and skill file. This CI workflow ensures that markdown files conform to expected schemas and that plugin metadata is complete before changes reach users.

Advanced Patterns: Orchestration and Sub-Skills

Complex workflows leverage hierarchical skill composition rather than hard-coded procedures. The tres-finance-plugin/skills/tres-onboarding/SKILL.md illustrates this pattern by declaring sub-skills that it orchestrates during execution.

When a user invokes /tres-onboarding, the primary skill coordinates multiple sub-skills—such as tres-asset-balance-validation and tres-ledger-link—sequentially. Each sub-skill runs its own markdown-defined logic, allowing the onboarding pipeline to maintain consistent validation rules across steps without centralized procedural code. This approach enables workflow reuse; individual sub-skills can be called independently or composed into different parent workflows.

Installing and Using Skills in Practice

The skills-based architecture provides a consistent interface for installation and invocation across all plugins.

Installing from the Marketplace

To add a plugin from the community repository:

# Add the community marketplace registry

claude plugin marketplace add anthropics/claude-plugins-community

# Install the QuickDesign plugin

claude plugin install quickdesign@claude-community

The CLI reads .claude-plugin/marketplace.json to locate the quickdesign entry, copies quickdesign/skills/quickdesign into ~/.claude/skills/quickdesign, and registers /quickdesign as an available slash command.

Invoking Skills in Chat

Once installed, skills are invoked through natural language requests that the model maps to slash commands:

User: I need a 30-second talking-avatar video for a new product launch.

Claude: Sure! Let me set that up.

/quickdesign video generate \
  --provider seedance \
  --reference-image product.jpg \
  --reference-image avatar.jpg \
  --duration 30 \
  --aspect-ratio 9:16 \
  -p '@Image2 in @Image1, says: "Check out our newest product!" No music score. No subtitles.' \
  -o launch.mp4 --wait

The model selects the quickdesign skill based on the request context and constructs the command using the syntax rules defined in the skill's markdown documentation.

Orchestrating Complex Workflows

For multi-step processes like financial entity onboarding:

User: Onboard the new subsidiary and set up its ledger.

Claude:
/tres-onboarding \
  --entity "NewCo Subsidiary" \
  --ledger "newco-ledger"

The tres-onboarding skill parses this request and sequentially invokes its declared sub-skills, each executing their own markdown-defined logic while the parent skill manages the overall workflow state.

Summary

• Skills are declarative markdown files (SKILL.md) with YAML front-matter that define capabilities as documentation rather than code
• Plugin manifests (plugin.json) and the marketplace index (marketplace.json) handle registration and discovery
• Runtime discovery scans skills/ directories to build slash commands dynamically at startup
• Orchestration allows skills to compose sub-skills hierarchically without hard-coded procedures
• CI validation ensures schema compliance before plugins reach users

Frequently Asked Questions

What file format do Claude plugins use to define skills?

Claude plugins define skills using SKILL.md files—markdown documents that combine YAML front-matter with rich documentation. The YAML header declares the skill name and description, while the markdown body contains the logic guidelines, cardinal rules, and parameter instructions that Claude follows when executing the skill.

How does Claude Code know which skills are available?

At startup, Claude Code scans the ~/.claude/skills/ directory for all SKILL.md files. It parses the YAML front-matter from each file to register slash commands (e.g., /quickdesign) and builds a skill graph that maps dependencies between capabilities.

Can skills call other skills in the Claude plugin architecture?

Yes, skills can declare and orchestrate sub-skills. For example, the tres-onboarding skill in the TRES Finance plugin coordinates multiple sub-skills (such as balance validation and ledger linking) to execute complex workflows. Each sub-skill runs its own markdown-defined logic, enabling reusable workflow components.

Where is the official list of community Claude plugins stored?

The official index lives in .claude-plugin/marketplace.json at the root of the anthropics/claude-plugins-community repository. This file is auto-generated from individual plugin.json manifests and is consumed by the CLI when users run claude plugin install commands.

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