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

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 followed by 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:

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 file defines basic metadata and component paths. Copy and modify this from any existing agent:

{
  "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 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

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 file points to the plugin's system prompt via the system.file field:

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 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 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 to propagate skill copies from the source vertical-plugins into your agent's bundle:

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 to verify manifests and resolve all file references:

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, a system prompt in agents/, and copied skills in skills/.
• Mirror the structure in managed-agent-cookbooks/<slug>/ with agent.yaml pointing to the same system prompt and optional leaf-worker subagents.
• Synchronize and validate by running scripts/sync-agent-skills.py to copy vertical-plugin skills into the bundle, then 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 performs a full repository lint that verifies manifest JSON validity, resolves all file references in plugin.json and 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.

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