Show Notes
Claude Code just got a big packaging upgrade: custom sub agents. Here’s what it actually means for building faster, safer AI-powered workflows and how to use it effectively.
What custom sub agents changed
- Teams of specialized agents: you can define multiple sub agents, each with a focused role (e.g., software architect, deployment engineer, payment integrator, data scientist).
- Per-agent context: each agent has its own conversation history and context, reducing cross-talk and confusing prompts.
- Scoped capabilities: you can grant each agent access to specific tools and code areas, making orchestration clearer and safer.
- Project vs. user scope: documents and front matter define how and where agents operate, with configurable access rules.
Roles you can define (examples)
- Software architect
- Deployment engineer
- Payment integrator
- Data scientist (Convex MCP-enabled example)
- Others as your project needs dictate
Key idea: you’re not just launching a single assistant, you’re building a small team of specialized agents that collaborate through a defined interface.
Docs, front matter, and the setup mindset
- Front matter for each agent: name, description, color (shown in the CLI), and role. This helps you skim and organize agents quickly.
- Per-agent context and conversation history: agents operate with their own context to reduce cross-agent confusion.
- MCP tooling awareness: some agents can be granted access to MCP tools (server-side capabilities) to run deployments, queries, and other privileged tasks.
- It’s not just about “more agents” — it’s about better structure and safer boundaries.
Code snippet (illustrative front matter):
yaml
---
name: "convex data scientist"
description: "Data analysis with Convex; MCP-enabled"
color: "#2B6CB0"
role: "data_scientist"
permissions:
mcp_tools: true
access: ["functions", "deployments", "tables", "var"]
tools:
- bash
- glob
- web_fetch
---
How the docs and docs-driven setup work
- Claude Code docs: you can train or reference docs to steer agent behavior and capabilities.
- Remote docs repo: a repo (Ghosty) mirrors Claude Code docs locally for offline, reliable access.
- Docs manifest and syncing: there’s a manifest.json that tracks what to pull and when; syncing can be automatic (e.g., every few hours) or manual.
- Practical example: point an agent at project docs to let it reason about the codebase from up-to-date docs, then run tasks like tests or analysis with the appropriate tools.
Tools, permissions, and what you can do
- Available tools (examples):
- bash and command execution
- deployments, tables, functions
- notebooks, web fetch, notetaking, and more
- Tool gating: you can grant access to a subset of MCP/internal tools, or omit tools to turn them all off.
- The difference between built-in APIs vs MCP: MCP is a server-side capability that lets agents invoke project-relevant commands and access data in a controlled way. It’s more than a simple API call—it’s a controlled execution environment.
Practical vibe: you can tailor each sub agent to your project’s toolbox, not just rely on generic prompts.
Demo takeaways and real-world flow
- Using docs to guide MCP-powered behavior: the approach lets you leverage the project’s own docs to shape how an agent understands and uses your codebase.
- Example workflow: a PR CI fail triggers a server-side agent with context to diagnose, propose fixes, or run tests, all while respecting defined boundaries.
- Augment vs. Claude Code trade-offs:
- Augment is strong for onboarding and large codebases where context gathering matters.
- Claude Code shines for running structured, tool-enabled tasks inside a controlled environment.
- Practical use-case explored: building a Convex data scientist agent with MCP access to Convex tools (functions, deployments, tables, var) to analyze data and generate insights or code changes.
Note on notes: you can chain agents and hooks (e.g., an orchestrator spawns sub agents in response to repo changes), which can streamline complex tasks but also requires mindful cost and context management.
Best practices and cautions
- Start small with cloud-generated agents: a solid foundation beats chasing “more agents” too soon.
- Be mindful of the dopamine effect: avoid spawning dozens of sub agents in one go; structure and validation matter.
- Context handling matters: plan how context is handed off between the orchestrator and sub agents to avoid stale or conflicting data.
- Think prompts aren’t magic: model training data and prompts influence behavior; set expectations about best practices and guardrails.
- Cost awareness: MCP-enabled workflows can rack up API/tool costs; measure usage against value.
Actionable takeaways
- Define a minimal, coherent first sub-agent (e.g., a data scientist for analytics with a restricted tool set) and iterate.
- Use per-agent front matter to keep roles, access, and tools explicit.
- Leverage docs as a knowledge source for agents to reduce wall-clock time and onboarding friction.
- Consider MCP-based agents for project-specific capabilities that require privileged operations (deployments, data access, specialized tooling).
- Balance augmentation and Claude Code usage to maximize productivity while keeping context manageable.
Links
- Claude Code Documentation (official docs and references)
- Claude Code GitHub Repository (example repo and plugins)
- Convex MCP Server Documentation (for setting up Convex-powered agents)
- Boris Cherny on X/Twitter (Claude Code creator updates)
If you want, I can tailor these notes to emphasize a particular workflow (e.g., onboarding a new codebase, CICD automation, or data analysis with MCP-enabled agents) and add more concrete code snippets or commands.