How to Activate Specific Skills in Garden-Skills: A Complete Guide for AI Agents

Agents activate specific skills by sending a request containing the skill name exactly as declared in the skill's manifest.json file, which the runtime resolves through a manifest-driven lookup to validate compatibility and execute the skill's entry points.

The ConardLi/garden-skills repository provides a modular framework where each skill is a self-contained folder under skills/. When agents such as Claude, Cursor, Codex, Gemini, or Opencode need to activate specific skills, they rely on a standardized manifest system that eliminates hard-coded paths and enables dynamic discovery.

The Manifest-Driven Activation System

Every skill in the repository follows a strict folder structure. Inside each skill directory (e.g., skills/web-video-presentation), a manifest.json file serves as the single source of truth. This file declares the skill's metadata, including its name, version, category, description, and critically, the compat array listing compatible agents: claude-code, claude-ai, cursor, codex-cli, gemini-cli, and opencode.

Anatomy of a Skill Manifest

The manifest file determines whether an agent can legally activate the skill. Here is the structure found in skills/*/manifest.json:

{
  "name": "web-video-presentation",
  "version": "1.0.0",
  "category": "content-generation",
  "description": "Generates interactive web presentations",
  "compat": ["claude-code", "claude-ai", "opencode", "cursor"]
}

Agents must reference the "name" field exactly when requesting activation. The runtime then validates the requesting agent against the "compat" array before proceeding.

The Four-Step Activation Flow

When an agent initiates a request to activate specific skills, the runtime executes this pipeline:

1. Locate the skill folder by matching the supplied name to a manifest.json file under skills/.
2. Validate compatibility by checking the "compat" array in the manifest against the current agent identifier.
3. Load entry points (scripts, TypeScript/React components, or command-line tools) found in the same skill folder.
4. Execute the skill in the context of the agent's request, returning generated output such as HTML presentations, design mock-ups, or knowledge-base retrievals.

Activation Methods by Agent Interface

Different agent interfaces use distinct invocation patterns, but all rely on the same underlying manifest resolution mechanism implemented in scripts/release/lib/skills.mjs.

Opencode CLI Activation

The Opencode toolchain provides direct CLI access to activate specific skills using the --skill flag:

# Activate the web-video-presentation skill

opencode run --skill web-video-presentation \
  --input "Create a 5-slide presentation about garden design."

The CLI performs three operations: it locates skills/web-video-presentation/manifest.json, verifies that "opencode" appears in the "compat" array, and executes the skill's React/TypeScript scaffold to return HTML output.

Claude Tool Calling

Claude-based agents (both claude-code and claude-ai) activate skills through structured tool calls. The .claude-plugin/marketplace.json file registers available skills for Claude's tool-use system:

{
  "name": "activateSkill",
  "arguments": {
    "skill": "kb-retriever",
    "query": "What are the best practices for PDF extraction?"
  }
}

Claude's tool wrapper extracts the kb-retriever identifier, loads skills/kb-retriever/manifest.json, confirms compatibility with "claude-code" or "claude-ai", and forwards the request to the skill's Python scripts (e.g., skills/kb-retriever/scripts/convert_pdf_to_images.py).

Cursor and Codex Prompt Integration

For Cursor and Codex, agents parse natural language prompts to extract skill names. When a prompt contains "Use the web-design-engineer skill to redesign this page", the integration layer extracts web-design-engineer, locates its manifest, and invokes the skill's React scaffold.

Gemini CLI Usage

Gemini CLI users activate specific skills using the --skill parameter:

gemini --skill gpt-image-2 generate --prompt "A modern garden layout"

The Gemini runtime resolves the skill name via manifest.json and executes the associated Node scripts found in the skill folder.

Programmatic Skill Activation

Developers can activate specific skills dynamically within JavaScript or TypeScript applications using the runtime's loadSkill function:

import { loadSkill } from '@garden-skills/runtime';

// Dynamically load a skill by name
const skill = await loadSkill('web-design-engineer');

// Call the skill's exported function
const result = await skill.apply({
  html: '<div>Hello</div>',
  styleGuide: 'modern',
});

console.log(result); // → redesigned HTML/CSS output

This helper reads the appropriate manifest.json, validates compatibility against the current execution context, and dynamically imports the skill's source modules.

Key Files in the Activation Pipeline

Several critical files govern how agents activate specific skills:

• skills/*/manifest.json: Declares skill metadata and compatible agents. The runtime scans these files to build the lookup table.
• scripts/release/lib/skills.mjs: Aggregates all manifests from the skills/ directory, providing the runtime lookup table used by all agent interfaces.
• .claude-plugin/marketplace.json: Registers skills specifically for Claude-based agents, enabling tool-call activation through Claude's plugin system.
• skills/*/SKILL.md: Contains detailed documentation for each skill, including parameters, examples, and operational limits.

Summary

• Agents activate specific skills by referencing the exact skill name declared in manifest.json.
• The compat array in each manifest restricts which agents (Claude, Cursor, Codex, Gemini, Opencode) can execute the skill.
• The runtime in scripts/release/lib/skills.mjs handles manifest scanning and validation automatically.
• Activation methods vary by interface: CLI flags for Opencode and Gemini, tool calls for Claude, and prompt parsing for Cursor/Codex.
• Adding new skills requires only creating a folder with a valid manifest.json; no agent code changes are necessary.

Frequently Asked Questions

What happens if an incompatible agent tries to activate a skill?

The runtime checks the "compat" array in manifest.json before execution. If the requesting agent is not listed (e.g., a Gemini CLI attempting to use a skill restricted to ["claude-code", "cursor"]), the activation fails with a compatibility error, preventing unauthorized execution.

Can skills be activated without knowing the exact folder path?

Yes. Agents only need to know the skill name as defined in the manifest. The runtime automatically resolves the folder location by scanning skills/ for matching manifest.json files, eliminating the need for hard-coded paths in agent configurations.

How does the Opencode toolchain differ from Claude in skill activation?

Opencode uses direct CLI commands with the --skill flag to trigger execution immediately, while Claude uses a tool-calling interface where the skill activation is a function call within a conversation. Both methods ultimately rely on the same manifest validation logic but differ in request formatting and invocation context.

Where is the skill compatibility list maintained?

The compatibility list is maintained in each skill's individual manifest.json file under the "compat" key. Additionally, .claude-plugin/marketplace.json provides a centralized registry for Claude-specific deployments, while scripts/release/lib/skills.mjs aggregates these for runtime validation.

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