# How the Description Field in SKILL.md Drives Skill Activation in Garden-Skills

> Understand how the description field in SKILL.md activates skills in Garden-Skills. Learn how it matches user intent to the right skill for seamless automation.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: internals
- Published: 2026-09-02

---

**The `description` field in each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file serves as the single source of truth that the Garden-Skills harness uses to recognize and activate the appropriate skill by matching user intent against the description text.**

The Garden-Skills repository implements a metadata-driven architecture where skill discovery depends entirely on YAML frontmatter in markdown files. When a user requests a task, the core skill-loader located in `scripts/release/lib/skills.mjs` parses every [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file to extract the `description` field. This plain-text string is then presented to the LLM as part of the system prompt, enabling semantic matching between the user's request and available capabilities.

## The Five-Step Skill Activation Pipeline

The description-driven activation workflow follows a strict pipeline from file system to LLM inference. Understanding each phase helps clarify why the wording of your `description` field directly impacts activation accuracy.

### 1. Discovery Phase

The skill discovery process begins in `scripts/release/lib/skills.mjs`, which walks the `skills/**/SKILL.md` directory tree using glob patterns. The script utilizes the `gray-matter` library to parse YAML frontmatter from each markdown file, extracting the `name` and `description` fields into a lightweight metadata object.

```javascript
// scripts/release/lib/skills.mjs – discovery excerpt
import fs from 'fs';
import matter from 'gray-matter';
import { glob } from 'glob';

const skillFiles = glob.sync('skills/**/SKILL.md', { cwd: process.cwd() });

const skillIndex = skillFiles.map(path => {
  const raw = fs.readFileSync(path, 'utf8');
  const { data } = matter(raw);  // Extracts YAML frontmatter
  return {
    name: data.name,
    description: data.description,
    path,
  };
});

```

### 2. Indexing and Caching

Once extracted, the name-description pairs are cached in memory (or serialized to a small JSON file) to ensure O(1) lookup performance during active conversations. This indexing step prevents redundant file system operations and allows the harness to present the complete skill catalog to the LLM instantaneously.

### 3. LLM Prompt Construction

When the agent needs to select a skill, the harness dynamically constructs a system prompt containing the available skill catalog. The prompt lists each skill's `name` followed by its `description`, formatted for optimal LLM comprehension.

```text
Available skills:
• beautiful-article – 把用户提供的素材（网页 URL / PDF / DOCX / …）编辑成单文件 HTML 网页文章
• web-video-presentation – 把一篇文章或口播稿做成“看起来像视频”的点击驱动 16:9 网页演示
• web-design-engineer – Build or redesign polished browser-rendered visual artifacts

```

### 4. Intent Matching

The LLM (Claude, GPT-4, etc.) performs semantic similarity matching between the user's request and the provided descriptions. For example, when a user asks *"Make a beautiful article from this PDF"*, the LLM recognizes that the `beautiful-article` description contains the most semantically aligned keywords and selects that skill.

```javascript
// Conceptual similarity matching (simplified)
function pickSkill(userPrompt, skillIndex) {
  const scores = skillIndex.map(s => ({
    skill: s,
    score: similarity(userPrompt, s.description), // Semantic comparison
  }));
  scores.sort((a, b) => b.score - a.score);
  return scores[0].skill; // Returns highest-scoring skill metadata
}

```

### 5. Skill Activation

After selection, the corresponding skill's [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) (or its internal [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) configuration) drives the subsequent workflow execution. The system also surfaces the selected `description` to the user as a confirmation blurb, ensuring transparency before heavy processing begins.

## Technical Implementation in skills.mjs

The `scripts/release/lib/skills.mjs` file serves as the central orchestrator for description parsing. It relies on the `matter()` function from `gray-matter` to extract the YAML frontmatter without loading the entire skill implementation into memory.

Key implementation details from the source:

- **File pattern**: `skills/**/SKILL.md` glob pattern ensures recursive discovery
- **Parsing**: `matter(raw)` returns a `data` object containing `name`, `description`, and other metadata
- **Storage**: The resulting array of objects is cached to prevent repetitive disk I/O
- **Export**: The module exposes this index to the prompt construction layer

The harness performs **no runtime parsing of the description** other than string retrieval and comparison, meaning the exact wording in the YAML frontmatter directly determines match quality.

## Multilingual Support and Description Quality

Because the `description` field accepts plain-text without structural constraints, the Garden-Skills repository supports both English and Chinese descriptions natively. As evidenced in files like [`skills/beautiful-article/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/SKILL.md) and [`skills/web-video-presentation/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/SKILL.md), descriptions can be written in whichever language best conveys the skill's capability.

This flexibility requires careful attention to description quality:

- **Specificity matters**: Vague descriptions like *"Handles documents"* yield poor matching accuracy compared to *"Converts PDF and DOCX files into single-file HTML articles"*
- **Keyword alignment**: The description should mirror the vocabulary users naturally employ when requesting the capability
- **Length optimization**: While the system accepts any length, concise descriptions (50-200 characters) typically produce more reliable LLM matching than verbose paragraphs

## Summary

- The `description` field in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) acts as the primary signal for skill recognition in the Garden-Skills architecture.
- `scripts/release/lib/skills.mjs` uses `gray-matter` to parse YAML frontmatter and build an indexed catalog of skill metadata.
- The LLM performs semantic matching between user prompts and skill descriptions to determine activation targets.
- Description content directly influences activation accuracy because the harness performs no post-processing or semantic interpretation of the text.
- Both English and Chinese descriptions are supported, with the plain-text format stored in `skills/**/SKILL.md` files.

## Frequently Asked Questions

### How does the system extract the description field from SKILL.md files?

The extraction occurs in `scripts/release/lib/skills.mjs` using the `gray-matter` npm package. The script reads each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file as UTF-8 text, passes the raw content through `matter()` to isolate the YAML frontmatter, and destructures the resulting `data` object to obtain the `description` string. This process runs during the discovery phase and caches results to avoid repeated file system operations.

### What happens if two skills have similar descriptions?

When description similarity creates ambiguity, the LLM's semantic matching determines the winner based on subtle linguistic differences and context clues from the user's full prompt. To prevent collisions, maintain distinct, capability-specific descriptions that emphasize unique aspects of each skill. The system does not implement manual disambiguation logic—it relies entirely on the LLM's ability to differentiate between the provided text strings.

### Can skill descriptions include Markdown formatting or HTML?

No. While the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file itself uses markdown, the `description` field within the YAML frontmatter should remain plain text. The Garden-Skills harness treats the description as a literal string for LLM matching and user display. Including markdown syntax (like `**bold**` or `[links]`) or HTML tags may interfere with semantic similarity algorithms and will render literally in skill selection UIs rather than formatting.

### Where is the skill catalog exposed to end users?

The compiled skill metadata, including descriptions, appears in [`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json) for Claude plugin integration and in dynamically generated system prompts shown to the LLM. Additionally, `scripts/release/list-skills.mjs` provides a debugging utility that prints all names and descriptions to the console, allowing developers to verify their [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) frontmatter renders correctly in the index.