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

The description field in each 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 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.

// 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.

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.

// 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 (or its internal 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 and 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 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 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 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 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 frontmatter renders correctly in the index.

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