# How to Create a New Agent from Scratch Using the Cookbook Structure in Financial Services

> Learn to create a new agent from scratch using the cookbook structure in financial services. Scaffold a plugin, mirror it, and sync skills for efficient development.

- Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services)
- Tags: how-to-guide
- Published: 2026-05-07

---

**To create a new agent from scratch using the cookbook structure, scaffold a self-contained plugin in `plugins/agent-plugins/<slug>/`, mirror it in `managed-agent-cookbooks/<slug>/`, and execute [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) followed by [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to validate cross-references and skill synchronization.**

The anthropics/financial-services repository implements every workflow agent as both a **Claude Cowork plugin** and a **Managed-Agent cookbook**. When you create a new agent from scratch using this cookbook structure, you establish a self-contained plugin directory with bundled skills and a parallel cookbook entry that enables headless orchestration.

## Step 1: Create the Agent Plugin

Begin by creating a directory under `plugins/agent-plugins/<your-slug>/` that contains the plugin metadata, system prompt, and bundled skills. According to the repository source code, this directory must be fully self-contained.

### Directory Structure

Create the following scaffold:

```text
plugins/
└─ agent-plugins/
   └─ my-agent/
      ├─ .claude-plugin/
      │   └─ plugin.json          # Plugin metadata (name, version, description)

      ├─ agents/
      │   └─ my-agent.md          # Canonical system prompt defining the agent's workflow

      └─ skills/
          ├─ skill-1/
          │   └─ SKILL.md
          └─ skill-2/
              └─ SKILL.md

```

### Key Files

The [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) file defines basic metadata and component paths. Copy and modify this from any existing agent:

```json
{
  "name": "my-agent",
  "description": "A custom financial-services workflow agent",
  "version": "0.1.0",
  "components": {
    "system": {
      "file": "agents/my-agent.md"
    },
    "skills": {
      "path": "skills"
    }
  }
}

```

The [`agents/my-agent.md`](https://github.com/anthropics/financial-services/blob/main/agents/my-agent.md) file contains the **system prompt** that defines the agent's end-to-end workflow, including its knowledge domain, communication style, and security constraints.

The `skills/` directory must contain **copies** of the skills the agent requires from the vertical plugins. As implemented in the financial-services repository, these are duplicated into the agent bundle rather than referenced directly to ensure deployment stability.

## Step 2: Add the Managed-Agent Cookbook

Mirror the plugin structure in `managed-agent-cookbooks/<your-slug>/` to enable headless orchestration and API deployment. The README notes that the **cookbook mirrors the plugin** and that the deploy script resolves these references automatically.

### Cookbook Structure

```text
managed-agent-cookbooks/
└─ my-agent/
   ├─ agent.yaml                 # References the same system prompt as the plugin

   ├─ subagents/                 # (Optional) Leaf-worker definitions for delegation

   └─ steering-examples.json    # Example events for programmatic invocation

```

### Configuration Details

The [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/agent.yaml) file points to the plugin's system prompt via the `system.file` field:

```yaml
name: my-agent
system:
  file: ../../plugins/agent-plugins/my-agent/agents/my-agent.md
skills:
  path: ../../plugins/agent-plugins/my-agent/skills
callable_agents:
  manifest: []          # Add leaf-worker subagents if delegation is required

```

*See [`managed-agent-cookbooks/pitch-agent/agent.yaml`](https://github.com/anthropics/financial-services/blob/main/managed-agent-cookbooks/pitch-agent/agent.yaml) for a full reference implementation.*

**Subagents** (depth-1 leaf workers) can be added under `subagents/` if you want the Managed-Agent to delegate specific tasks. The [`steering-examples.json`](https://github.com/anthropics/financial-services/blob/main/steering-examples.json) file shows how a client would invoke the agent programmatically.

## Step 3: Run the Sync and Lint Checks

After creating the directory structures and adding skill folders, execute the maintenance scripts to ensure skill synchronization and reference integrity.

### Synchronize Agent Skills

Run [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) to propagate skill copies from the source vertical-plugins into your agent's bundle:

```bash
python3 scripts/sync-agent-skills.py

```

This script copies any skill listed under `plugins/vertical-plugins/*/skills/` into every agent bundle that references them, preventing drift between source definitions and deployed agents.

### Validate with Check Script

Execute [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to verify manifests and resolve all file references:

```bash
python3 scripts/check.py

```

The linter performs a full repository validation—it aborts if any bundled skill is out-of-sync or if a manifest reference is broken. When both commands finish without error, your new agent is ready for installation as either a **Claude Cowork plugin** or a **Managed-Agent**.

## Summary

- **Create the agent plugin** in `plugins/agent-plugins/<slug>/` with [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json), a system prompt in `agents/`, and copied skills in `skills/`.
- **Mirror the structure** in `managed-agent-cookbooks/<slug>/` with [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/agent.yaml) pointing to the same system prompt and optional leaf-worker subagents.
- **Synchronize and validate** by running [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) to copy vertical-plugin skills into the bundle, then [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to verify all references and manifests.

## Frequently Asked Questions

### What is the difference between the agent plugin and the Managed-Agent cookbook?

The **agent plugin** is a self-contained directory under `plugins/agent-plugins/` that bundles the system prompt and skills for Claude Cowork plugin installation. The **Managed-Agent cookbook** is a parallel structure under `managed-agent-cookbooks/` that references the same files but adds configuration for headless API deployment and optional subagent delegation.

### How do I keep agent skills synchronized with changes to vertical plugins?

Run `python3 scripts/sync-agent-skills.py` after modifying any skills in `plugins/vertical-plugins/*/skills/`. This script propagates copies of skills into every agent bundle that uses them, ensuring no drift occurs between source definitions and deployed agents.

### Can I deploy an agent without creating a cookbook entry?

No. According to the financial-services repository structure, the deploy script resolves references through the cookbook entry. While the plugin structure alone supports Claude Cowork installation, the **Managed-Agent cookbook** is required for headless orchestration and API-based deployment.

### What does the check.py script validate?

[`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) performs a full repository lint that verifies manifest JSON validity, resolves all file references in [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) and [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/agent.yaml) files, and confirms that bundled skills are synchronized with their source vertical-plugins. It aborts with error details if any reference is broken or if skill drift is detected.