How the Agent Decides Which Skill Pack to Use in Garden Skills

The agent selects a skill pack through a two-step process: first registering available plugin packs via .claude-plugin/marketplace.json, then matching the user's request intent against the description field in each skill's SKILL.md frontmatter.

The Garden Skills repository (ConardLi/garden-skills) provides a modular framework for AI coding agents including Claude Code, Cursor, and Codex. Understanding how the agent decides which skill pack to use is essential for developers customizing AI workflows or building custom skill packs.

The Two-Step Selection Mechanism

According to the Garden Skills source code, the agent employs a deterministic, data-driven pipeline to activate the correct skill pack. This process separates the discovery of available packs from the semantic matching of user intent.

Step 1: Plugin Pack Declaration

The repository defines plugin packs in .claude-plugin/marketplace.json. This JSON file serves as the registry that tells the agent where each skill lives on disk.

Each pack entry groups one or more skills and maps the pack name to a specific directory. For example, the web-design-skills pack points to the folder ./skills/web-design-engineer and includes the entire skill contents ("./"). When a user installs a pack via the Claude Code marketplace (e.g., /plugin install web-design-skills@garden-skills) or the CLI, the agent registers the pack and its contained skills in the local environment.

The marketplace.json file acts as the single source of truth for pack availability and filesystem location.

Step 2: Skill Activation via Description

Inside every skill folder, a mandatory SKILL.md file contains the activation logic in its frontmatter. Specifically, the description field acts as the contract between the skill and the agent.

When the agent receives a user request, it parses the intent and compares it against the description text in each registered skill's SKILL.md. If the description semantically matches the request—for example, a description like "Design / Frontend – best for web pages, landing pages, dashboards..." matching a request to "Create a landing page"—the agent selects that skill automatically.

As documented in README.md (lines 73-76): “The agent decides whether to activate the skill from the description line in the frontmatter — so the description is the contract between you and the agent.”

The agent does not evaluate file names or folder paths during selection. The description field is the sole decision point.

Practical Installation and Activation Flow

The complete selection workflow operates as follows:

1. Install – The user installs a pack using the CLI (npx skills add ...), a marketplace command (/plugin install), or manual copy. The pack's entry in .claude-plugin/marketplace.json tells the agent where the skill directory resides.

2. Scan Request – The agent receives a user prompt, parses the intent, and queries the description fields in all registered SKILL.md files.

3. Activate Skill – Upon finding a matching description, the agent loads the skill's SKILL.md and any associated assets from scripts/ or references/ directories.

4. Fallback – If no description matches the request intent, the agent falls back to "no-skill" mode and proceeds with its own base logic.

Code Examples

Install the web-design-skills pack using the Claude Code marketplace:

/plugin install web-design-skills@garden-skills

Install a single skill using the agent-agnostic CLI:

npx skills add ConardLi/garden-skills -s gpt-image-2

Perform a manual installation for custom builds:

git clone https://github.com/ConardLi/garden-skills.git
cp -r garden-skills/skills/web-design-engineer .claude/skills/

When the agent receives a request like:

“Create a landing page with a modern design system and responsive layout.”

It reads the description in skills/web-design-engineer/SKILL.md and activates that skill pack automatically.

Key Files in the Selection Process

• .claude-plugin/marketplace.json – Declares plugin packs and maps them to skill directories on disk.
• skills/*/SKILL.md (e.g., skills/web-design-engineer/SKILL.md) – Contains the description frontmatter field used for intent matching and activation.
• README.md – Documents the contract mechanism and selection logic (specifically lines 73-76).
• package.json – Provides the entry point for the npx skills CLI installation commands.

Summary

• The agent discovers available skills through .claude-plugin/marketplace.json, which registers pack locations.
• Selection depends entirely on the description field in each skill's SKILL.md frontmatter.
• File names and directory structures are ignored during the matching process.
• If no description matches the user intent, the agent falls back to default behavior without activating any skill pack.
• Installation can occur via Claude Code marketplace commands, the npx skills CLI, or manual filesystem operations.

Frequently Asked Questions

What file does the agent read to find available skill packs?

The agent reads .claude-plugin/marketplace.json to discover registered plugin packs. This file maps pack names (like web-design-skills) to their corresponding directories (like ./skills/web-design-engineer).

Can the agent select a skill based on its filename or folder name?

No. According to the Garden Skills source code, the agent does not consider file names or folder paths when selecting a skill. It relies exclusively on the description field in the SKILL.md frontmatter to match user intent.

What happens if no skill description matches the request?

If the agent cannot find a description field that matches the parsed intent of the user request, it falls back to "no-skill" mode. In this state, the agent proceeds using its own internal logic without loading any specialized skill assets.

How do I install a skill pack in Claude Code?

You can install a skill pack using the marketplace command /plugin install <pack-name>@garden-skills, or use the CLI tool with npx skills add ConardLi/garden-skills -s <skill-name>. Both methods register the pack in .claude-plugin/marketplace.json and make its skills available for selection.

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