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

> Discover Claude plugins' skills-based architecture. Learn how declarative markdown defines AI capabilities and powers dynamic workflows. Explore the anthropics/claude-plugins-community repo.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: architecture
- Published: 2026-08-24

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), a generated registry of all community plugins. This file aggregates every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), including parameter validation and output formatting rules.

### Runtime Validation

The repository includes [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```bash

# 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)) with YAML front-matter that define capabilities as documentation rather than code
- **Plugin manifests** ([`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)) and the **marketplace index** ([`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) at the root of the `anthropics/claude-plugins-community` repository. This file is auto-generated from individual [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifests and is consumed by the CLI when users run `claude plugin install` commands.