What Are Agent Skills in Garden Skills? A Modular Framework for Specialized AI Agents

Agent skills in Garden Skills are reusable, self-contained "skill packs" that transform generic AI coding agents into domain specialists by providing structured system prompts, checkpoint-controlled workflows, and on-demand reference materials.

The ConardLi/garden-skills repository implements a standardized architecture for agent skills, turning general-purpose LLMs like Claude Code or Cursor into disciplined experts. Each skill resides under skills/<skill-name>/ and follows a strict layout that constrains the agent's behavior, ensuring repeatable, high-quality outputs for specific design and data-driven tasks.

Anatomy of an Agent Skill

Every agent skill follows a predictable file structure that separates concerns between prompts, metadata, knowledge, and utilities.

SKILL.md: The System Prompt Core

At the heart of every skill lies SKILL.md, located at skills/<skill-name>/SKILL.md. This file serves as the system prompt that defines the agent's role, workflow stages, hard rules, and decision checkpoints. Written in YAML front-matter and Markdown, it is read by the host-side agent loader to configure the AI's behavior.

For example, skills/web-design-engineer/SKILL.md establishes the agent as a design engineer, enforcing workflows like "understand requirements → design read → v0 draft → full build → verification."

Agent Metadata (agents/*.yaml)

The agents/ directory contains host-facing metadata that controls how the skill appears and initializes. Files like skills/web-design-engineer/agents/openai.yaml specify the display name, description, and the default prompt injected when the skill is activated. This separation allows the same skill core to work across different agent hosts with host-specific optimizations.

On-Demand Reference Materials

Instead of loading entire codebases into context, agent skills use the references/ directory for targeted knowledge retrieval. These small, focused knowledge bases include style recipes, design direction tables, and anti-cliché checklists that the skill loads only when needed.

For instance, when a user requests a "Linear-style" design, the agent reads only references/style-recipes/linear.md rather than the full catalog. This reference-on-demand approach keeps token budgets low while maintaining deep expertise. Other examples include references/CHAPTER-CRAFT.md for video presentation skills and references/pdf_reading.md for knowledge-base retrieval tasks.

Template Scaffolds and Utilities

The templates/ directory contains scaffold scripts, CI helpers, and bootstrap utilities that the skill invokes during execution. The web-video-presentation skill, for example, includes templates/scripts/scaffold.sh to initialize project structures, while the kb-retriever skill provides scripts/convert_pdf_to_images.py for document processing.

How Agent Skills Transform Generic Agents into Specialists

When a user requests a specialized task—such as "design a landing page"—the host system searches for a matching skill folder. Upon finding skills/web-design-engineer/, the host automatically imports the SKILL.md prompt, injects relevant reference files (like a specific style recipe), and initiates the workflow described in the skill.

This process eliminates generic AI pitfalls by constraining outputs through checkpoint-controlled execution. The agent must pause at hard nodes (e.g., "Checkpoint Plan" in the video-presentation skill) for user confirmation before proceeding, ensuring the output aligns with requirements at every stage.

Core Architectural Principles

Agent skills are deliberately engineered for modularity and control through four key design patterns:

• Scope-Driven Boundaries: Each skill explicitly declares what it can and cannot do in the "Scope" section of SKILL.md, preventing capability drift.
• Checkpoint-Controlled Workflows: Hard nodes force the agent to pause for user validation, such as the "Checkpoint Plan" requirement in skills/web-video-presentation/SKILL.md.
• Reference-on-Demand Loading: Only necessary reference files enter the context window (e.g., loading a single linear.md style recipe), optimizing token usage.
• Self-Checking Mechanisms: Every major output runs through built-in validation checklists defined in the skill's SKILL.md, such as verifying that "no rogue colors or fonts outside the declared design system" were used.

Implementation: Loading and Executing Agent Skills

The following pseudo-code illustrates how a host application loads and executes an agent skill:

# Pseudo-code for a host that runs an AI agent

skill_path = "./skills/web-design-engineer"
system_prompt = read_file(f"{skill_path}/SKILL.md")
agent = AIChatModel(system_prompt)

# The agent now follows the web-design-engineer workflow

response = agent.ask("Design a product-page for a new coffee brand")
print(response)

Inside SKILL.md, reference loading is triggered by specific user inputs. This YAML excerpt from web-design-engineer/SKILL.md shows how style recipes are accessed:

# In web-design-engineer/SKILL.md

...

### Step 2 – Gather Design Context (by priority)

...
4. User names an anchor ("Linear-style" / "Aesop feeling") → read the single recipe file at
   `references/style-recipes/<anchor>.md` (e.g., `references/style-recipes/linear.md`).
...

Finally, skills enforce quality through structured self-checklists embedded in the markdown:

## Pre-delivery Checklist

- [ ] **Step 0 ran** – verified product/brand facts via web search
- [ ] Design Read exists; five dials influence real decisions
- [ ] No rogue colors or fonts outside the declared design system
- [ ] No emoji or left-border accent cards unless the brand spec allows it
- [ ] All hard rules (e.g., no `const styles = {…}`) are respected

Summary

• Agent skills are modular configurations stored under skills/<skill-name>/ that convert generic LLMs into task-specific specialists.
• Each skill requires SKILL.md (system prompt), optional agents/*.yaml (host metadata), references/ (on-demand knowledge), and templates/ (utilities).
• The architecture emphasizes checkpoint-controlled workflows and reference-on-demand loading to maintain quality while managing token budgets.
• Skills are self-contained, version-controllable, and extensible without modifying the underlying agent runtime.
• Built-in self-checklists ensure outputs adhere to brand specifications and hard constraints defined in the skill configuration.

Frequently Asked Questions

What distinguishes agent skills from standard system prompts?

Unlike static system prompts, agent skills provide a complete operational framework including checkpoint-controlled workflows, on-demand reference loading, and self-validation checklists. According to the Garden Skills source code, a skill is not just a persona but a "reusable, self-contained skill pack" with strict directory structures (skills/<skill-name>/) that guide the agent through multi-stage executions with forced validation points.

How do agent skills handle large knowledge bases without exceeding token limits?

Agent skills implement reference-on-demand architecture. Rather than loading entire repositories into context, the skill loads only specific files from the references/ directory when triggered by user input. For example, requesting a "Linear-style" design loads only references/style-recipes/linear.md, not the full style catalog, preserving the token budget for actual task execution.

Can I create a custom agent skill for specialized business workflows?

Yes. Adding a new capability requires creating a directory under skills/ that follows the established layout: a SKILL.md with YAML front-matter defining workflows and checkpoints, optional agents/*.yaml for host integration, and relevant references/ or templates/ as needed. Because skills are plain Markdown and YAML, they can be version-controlled and reviewed through standard git workflows without modifying the agent runtime.

What role do checkpoints play in agent skill execution?

Checkpoints are hard constraints defined in SKILL.md that force the agent to pause for user confirmation before proceeding to subsequent stages. As implemented in skills like web-video-presentation, checkpoints (e.g., "Checkpoint Plan") ensure that preliminary outputs meet requirements before the agent invests tokens in full implementation, preventing costly revisions and maintaining alignment with user intent.

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