What Is the Role of SKILL.md in Activating a Garden Skill?

SKILL.md serves as the canonical activation blueprint that the Instagit runtime reads to discover, identify, and execute Garden Skills through structured frontmatter metadata and deterministic workflow definitions.

In the ConardLi/garden-skills repository, the Instagit agent relies on a specific contract to activate autonomous capabilities. Every Garden Skill must include a SKILL.md file that functions not merely as documentation, but as the executable manifest defining how the skill is discovered, presented to users, and orchestrated through complex multi-phase workflows.

SKILL.md as the Garden Skill Activation Blueprint

The activation process centers on four distinct responsibilities that transform a markdown file into a runtime contract.

Skill Discovery and Identification

Activation begins when the Instagit agent scans the repository for SKILL.md files located under skills/<skill-name>/ directories. This discovery mechanism enables the runtime to build an index of available capabilities by detecting the canonical definition files. For example, the Web Video Presentation skill is located at skills/web-video-presentation/SKILL.md, while the Web Design Engineer skill resides at skills/web-design-engineer/SKILL.md.

Frontmatter Metadata Extraction

Upon locating a skill file, the runtime parses the YAML frontmatter to extract the name and description fields. These metadata properties serve dual purposes: they uniquely identify the skill for programmatic selection and provide human-readable explanations for user interfaces.

Example from the Web Video Presentation skill (lines 1-4):

---
name: web-video-presentation
description: 把一篇文章或口播稿，做成"看起来像视频"的点击驱动 16:9 网页演示，可选合成口播音频。
---

Similar patterns appear in the Beautiful Article skill (skills/beautiful-article/SKILL.md) and the KB Retriever skill (skills/kb-retriever/SKILL.md), each declaring their activation identity through this standardized header format.

Workflow Orchestration and Deterministic Execution

Beyond metadata, SKILL.md contains the embedded workflow that drives step-by-step execution. The markdown body defines procedural phases—from Phase 0 (Intake) through Phase 4 (Delivery)—and specifies hard checkpoints where the agent must pause for user confirmation.

The runtime parses these workflow sections to enforce deterministic behavior. For instance, the Web Video Presentation skill defines specific checkpoint titles like "Checkpoint Plan" and "Checkpoint Audio" (lines 25-86 and 126-200), which the Instagit agent translates into mandatory confirmation gates.

Resource Reference Mapping

SKILL.md provides the reference list of supporting resources that the skill's implementation reads on demand. These include scaffold scripts and supplementary documentation (e.g., references/*.md files) that the agent consults during specific phases. This resource mapping ensures that the activation blueprint remains self-contained while delegating specific implementations to external assets.

Runtime Implementation and Code Execution

When activating a skill, the Instagit runtime executes logic similar to the following Python pseudo-code:

# Locate SKILL.md files

skill_paths = glob("skills/**/SKILL.md")

# Load a specific skill (e.g., web-video-presentation)

skill_file = next(p for p in skill_paths if "web-video-presentation" in p)
metadata = yaml.safe_load(read_file(skill_file, 1, 4))

# Present choice to user

print(f"Skill: {metadata['name']}\n{metadata['description']}")

# Parse workflow sections

workflow = parse_markdown_sections(read_file(skill_file))
run_phase(workflow['Phase 0 – Intake'])

The read_file function extracts raw lines from the SKILL.md, while parse_markdown_sections splits the markdown into executable headings that map to specific runtime phases.

Enforcing Mandatory Hard Checkpoints

The activation blueprint enforces strict pause-for-confirmation behavior through checkpoint parsing. The runtime implements hard node rules by extracting checkpoint definitions directly from the SKILL.md content:

def run_checkpoint(name, required=True):
    # Show checkpoint description from SKILL.md

    print(f"⚡️ Checkpoint {name} – must pause for user confirmation")
    if required:
        answer = ask_user("Proceed? (yes/no) ")
        if answer.lower() != "yes":
            raise RuntimeError("User stopped the skill")

This implementation ensures that skills like GPT-Image-2 (skills/gpt-image-2/SKILL.md) and Web Design Engineer maintain deterministic execution paths, preventing autonomous progression past critical decision points without explicit user validation.

Summary

• SKILL.md functions as the activation blueprint for the Instagit runtime in the ConardLi/garden-skills repository, transforming markdown documentation into executable instructions.
• Discovery occurs through filesystem scanning of skills/<skill-name>/SKILL.md paths, enabling automatic indexing of available capabilities.
• Frontmatter metadata (name and description fields) provides both programmatic identification and user-facing explanations.
• Embedded workflows define deterministic execution paths from Phase 0 through Phase 4, including mandatory hard checkpoints that enforce pause-for-confirmation behavior.
• Hard checkpoints are parsed directly from the markdown sections and implemented as runtime gates that prevent autonomous progression without user validation.

Frequently Asked Questions

What makes a Garden Skill "activatable" by the Instagit system?

A Garden Skill becomes activatable when it includes a properly structured SKILL.md file under its skills/<skill-name>/ directory. This file must contain valid YAML frontmatter with name and description fields, along with the procedural workflow that guides the agent through execution phases. Without this canonical definition file, the Instagit runtime cannot discover or load the skill.

How does the Instagit agent use SKILL.md during execution?

The agent reads SKILL.md to extract metadata for user presentation, then parses the markdown body to identify phases and checkpoints. During execution, it maps these parsed sections to specific runtime functions, enforcing hard checkpoints by pausing for user confirmation when encountering titles like "Checkpoint Plan" or "Checkpoint Audio" extracted from the workflow definition.

What are hard checkpoints in SKILL.md and why are they required?

Hard checkpoints are specific sections within the SKILL.md workflow that mandate user confirmation before proceeding. They prevent deterministic drift by ensuring the agent cannot autonomously skip critical decision points. The runtime implements these by extracting checkpoint titles from the markdown and wrapping subsequent execution in confirmation gates that raise runtime errors if the user declines to proceed.

Can a skill function without a SKILL.md file in the ConardLi/garden-skills repository?

No. The repository architecture requires SKILL.md as the canonical skill definition. The Instagit agent specifically scans for these files to build the skill index, and the runtime depends on their frontmatter and workflow structure to execute any capability. Without this activation blueprint, the skill remains invisible to the discovery mechanism and unexecutable by the orchestration layer.

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