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

> Discover how the Claude Code plugin auto-discovers agents by scanning agent markdown files in the agents directory. Learn how Caveman simplifies agent registration for seamless integration.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```markdown
---
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:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.