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

> Learn how to activate specific skills in Garden-Skills. This guide explains the exact process agents use to request and execute skills via manifest-driven lookup for seamless AI agent functionality.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Agents activate specific skills by sending a request containing the skill name exactly as declared in the skill's [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`:

```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`](https://github.com/ConardLi/garden-skills/blob/main/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:

```bash

# 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json) file registers available skills for Claude's tool-use system:

```json
{
  "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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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:

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

```

The Gemini runtime resolves the skill name via [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/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:

```typescript
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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file under the `"compat"` key. Additionally, [`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json) provides a centralized registry for Claude-specific deployments, while `scripts/release/lib/skills.mjs` aggregates these for runtime validation.