How Agents Are Auto-Discovered by the Claude Code Plugin in Caveman

The Claude Code plugin auto-discovers agents by scanning the agents/ directory for Markdown files, treating each *.md file as a sub-agent without requiring manual registration in plugin.json.

The Caveman repository implements a streamlined auto-discovery mechanism that allows Claude Code plugins to dynamically load sub-agents from the filesystem. According to the source code in JuliusBrussee/caveman, this process relies on a simple convention-based approach where files placed in a specific directory automatically become available as sub-agents. This design eliminates the need for explicit manifest declarations while maintaining compatibility with both Claude Code and Opencode environments.

The Auto-Discovery Convention

Claude Code plugins follow a standard filesystem-based discovery pattern. When the Caveman plugin is installed, Claude Code automatically scans the plugin's agents/ directory and treats every top-level Markdown file (*.md) as a distinct sub-agent.

This behavior is documented in the repository's CLAUDE.md file, which specifies that the agents/ folder is scanned wholesale during plugin initialization. The discovery process requires zero configuration beyond creating the Markdown files themselves, making it trivial to add new capabilities by simply dropping files into the directory.

Required Configuration to Enable Discovery

To activate the default scanning behavior, the plugin's plugin.json manifest must not contain an agents array. According to the source code analysis, explicitly defining an agents array in the configuration disables the automatic directory scan, forcing manual registration of each sub-agent instead.

This design choice creates a clear binary option: either rely entirely on the auto-discovery mechanism by omitting the array, or explicitly opt out by defining the agents manually. For the Caveman plugin's auto-discovery to function, developers must leave the agents field undefined in the manifest.

How Sub-Agent Names Are Determined

When Claude Code processes each Markdown file in the agents/ directory, it derives the sub-agent's display name using a specific priority system:

1. Front-matter name field – The parser first checks for a name property in the YAML front-matter at the top of the Markdown file.

2. Filename fallback – If the front-matter field is missing, the system falls back to using the filename (without the .md extension) as the identifier.

This naming convention allows developers to create descriptive agent names independent of filesystem constraints while providing a sensible default based on the file itself.

Opencode Compatibility Layer

The Caveman repository extends this auto-discovery mechanism to support Opencode, which mirrors Claude Code's hook architecture but requires sanitization of Claude-specific metadata. The helper function transformOpencodeAgentFrontmatter in bin/lib/opencode-agent.js processes agent files to remove incompatible fields.

Specifically, the transformer strips tools: arrays and provider-less model: values that are valid in Claude Code but invalid in Opencode environments. When the Caveman plugin is used with Opencode, this compatibility layer ensures that agents discovered from the agents/ directory load correctly without manual front-matter editing.

Practical Implementation Example

Adding a new agent to the Caveman plugin requires only creating a Markdown file with appropriate front-matter. Here is the minimal structure for an agent definition:

---
name: Example Agent
model: haiku
---

You are a helpful assistant that always replies in pirate slang.

When installed, Claude Code automatically discovers this file in the agents/ directory. For Opencode deployments, the system automatically invokes the transformation helper to sanitize the front-matter:

const { transformOpencodeAgentFrontmatter } = require('./bin/lib/opencode-agent');
const raw = fs.readFileSync('agents/example-agent.md', 'utf8');
const fixed = transformOpencodeAgentFrontmatter(raw);
fs.writeFileSync('agents/example-agent.md', fixed);

The src/hooks/caveman-activate.js file handles the registration logic, triggering the auto-discovery process when Claude Code starts a new session. Because discovery depends purely on file presence, new sub-agents become instantly available without restarting the Claude Code application or updating manifest files.

Summary

• Filesystem-based discovery: Claude Code automatically scans the agents/ directory for *.md files when processing the Caveman plugin.

• Manifest requirements: Omitting the agents array from plugin.json is required to enable the default scanning behavior.

• Flexible naming: Sub-agent names derive from front-matter name fields or fall back to filenames.

• Cross-platform support: The bin/lib/opencode-agent.js utility sanitizes Claude-specific front-matter for Opencode compatibility.

• Zero-config addition: Adding agents requires only creating new Markdown files in the designated directory.

Frequently Asked Questions

What happens if I define an agents array in plugin.json?

Explicitly defining an agents array in plugin.json disables the automatic directory scan entirely. When the array is present, Claude Code switches to manual registration mode and only loads the agents explicitly listed in the manifest, ignoring any Markdown files in the agents/ directory.

Can I organize agents in subdirectories within the agents folder?

The auto-discovery mechanism described in CLAUDE.md specifies scanning for top-level Markdown files in the agents/ directory. While the documentation focuses on top-level files, the recursive scanning behavior depends on Claude Code's internal implementation. For guaranteed discovery, place agent files directly in the agents/ root rather than nested folders.

How do I make Caveman agents work with Opencode?

The Caveman repository includes automatic compatibility handling through bin/lib/opencode-agent.js. When deploying to Opencode, the installer uses the transformOpencodeAgentFrontmatter function to strip Claude-specific fields like tools: arrays and bare model: values. This transformation happens automatically during the installation process, requiring no manual intervention from developers.

What front-matter fields are supported for agent configuration?

Standard fields include the name property for agent identification and model for specifying the language model. The Caveman plugin passes through additional Claude Code-specific configuration options, though fields like tools: arrays are automatically filtered when converting for Opencode compatibility as documented in the transformation utility.

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