# What Are Agent Skills in Garden Skills? A Modular Framework for Specialized AI Agents > Discover agent skills in Garden Skills. Learn how these modular skill packs specialize AI agents with structured prompts, workflows, and reference materials. Transform your AI today. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: getting-started - Published: 2026-09-01 --- **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//` 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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), located at `skills//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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/references/CHAPTER-CRAFT.md) for video presentation skills and [`references/pdf_reading.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/templates/scripts/scaffold.sh) to initialize project structures, while the `kb-retriever` skill provides [`scripts/convert_pdf_to_images.py`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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: ```python # 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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), reference loading is triggered by specific user inputs. This YAML excerpt from [`web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/web-design-engineer/SKILL.md) shows how style recipes are accessed: ```yaml # 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/.md` (e.g., `references/style-recipes/linear.md`). ... ``` Finally, skills enforce quality through structured self-checklists embedded in the markdown: ```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//` that convert generic LLMs into task-specific specialists. - Each skill requires [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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//`) 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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.