When should I use a subagent and when a skill?

Use a subagent when you want work done in a separate context and only a summary of the results returned. Use a skill when you want to reuse set procedures or instructions within the main conversation.

Do subagents increase usage?

Subagents send their own requests, and these count toward the same usage limits as the main conversation. To keep costs down, the official documentation also suggests delegating tasks to subagents that use a faster, lower-cost model such as Haiku.

Build & sell

Building AI Employees with Claude Code: Subagents and Settings

Published Oct 2, 2026 ・ Employee Store Operations

Summary

In Claude Code, you can build AI employees for specific roles by combining configuration files, subagents, skills and hooks. This article explains what each mechanism does, based on the official documentation as checked in October 2026. It also covers how to let other people use the AI employees you build.

List your AI employee

The content of this article was checked against the official Claude Code documentation on October 2, 2026. Claude Code is updated often, and settings and screens may change. Before you rely on it, check the latest information through the sources at the end.

Building an AI employee with Claude Code means writing down the work rules, roles, procedures and actions to block in files, and setting things up so Claude works within those limits. You do not need to write a program from scratch. Most of it is decided in Markdown files and configuration files.

What Building an AI Employee with Claude Code Means

Claude Code is an AI tool that reads codebases, edits files and runs commands. It works in the terminal, IDEs, a desktop app and the browser. Most uses require a Claude subscription or an Anthropic Console account.

There are four main mechanisms for putting it to work as an AI employee. Their roles look like they overlap, but they differ in when they are loaded and how strongly they apply.

Mechanisms used to build AI employees (checked October 2026)
Mechanism	Where it lives	When it is loaded	Strength
CLAUDE.md	Project root and similar locations	At the start of every session	Read as instructions. Not enforced
Subagents	.claude/agents/	When a task matching the role is delegated	Can limit which tools are available
Skills	.claude/skills/<name>/SKILL.md	Body is read only when used	Read as instructions. Not enforced
Hooks and permissions	Settings files	Before and after tool use, etc.	Claude Code always executes them

Give Work Rules with CLAUDE.md

CLAUDE.md is a Markdown file where you write instructions you want Claude to follow every time. Claude reads this file at the start of each session. For a project, place it at ./CLAUDE.md or ./.claude/CLAUDE.md, and share it with your team through version control.

The official documentation describes it as the place for things you keep explaining again. Signs that you should add something are when the same mistake happens twice, or when new team members would need the same explanation. Running /init creates a first CLAUDE.md based on an analysis of your codebase.

Tips for Writing It

Write in concrete, verifiable terms. For example, write 'run npm test before committing'
Aim for under 200 lines per CLAUDE.md. Longer files use more context and are followed less reliably
Organize it with headings and bullet points. Do not leave conflicting instructions
Move long procedures, or rules that apply only to some files, into skills or path-specific rules

CLAUDE.md is read as context, not as an enforced setting. Block actions that must never happen with hooks or permission settings, explained later.

List your AI employee

Split Roles with Subagents

Subagents are AI assistants that handle specific tasks. Each has its own context window, system prompt, available tools and permissions. When a task matches a subagent's description, Claude delegates it. When the subagent finishes, it returns only a summary of the results.

They suit high-volume work whose output does not need to stay in the main conversation, such as research results or logs. Subagent usage counts toward the same usage limits as the main conversation.

Where to Put the Files and How to Write Them

A subagent is a Markdown file with YAML frontmatter. Put it in .claude/agents/ to use it in one project only, or in ~/.claude/agents/ to use it across all your projects. You can write the file yourself or ask Claude to write it.

name (required): the subagent's name
description (required): when to delegate to this subagent
tools: the tools it can use. If omitted, it inherits all tools available to subagents
model: the model to use. You can specify sonnet, opus, haiku and others
permissionMode, skills, hooks: permission behavior, skills loaded from the start, and hooks for this subagent only

Claude reads the description to decide whom to delegate to. So keep the description short and clear. Put detailed instructions in the body, which is read only when the subagent runs. For a read-only role, limit tools to read-only tools.

By default, subagents can start their own subagents down to 3 levels below the main conversation. For roles that should not do this, remove Agent from tools. We explain how to combine multiple subagents in Designing Multi-Agent Systems.

Package Procedures as Skills

A skill bundles a procedure or checklist into a file called SKILL.md. Claude uses skills when they are relevant, and people can call one directly with /skill-name. Unlike CLAUDE.md, the body is loaded only when it is used. Even long reference material uses almost no context until it is needed.

Put skills for all your projects in ~/.claude/skills/<name>/SKILL.md, and skills for one project in .claude/skills/<name>/SKILL.md. Commit project skills to share them with your team. The former custom commands have been merged into skills. For skills you do not want Claude to use on its own, disable-model-invocation makes them run only when a person calls them.

Decide where to write it

What do you want to tell your AI employee?

Facts or rules to follow every timeCLAUDE.mdKeep it short, under 200 lines as a guide

Long procedures or checklists used occasionallySkillsLoaded only when used

Work to hand off in a separate contextSubagentsOnly a summary comes back

Actions that must always be blockedHooks and permissionsClaude Code enforces them

Prevent Unwanted Actions with Hooks and Permissions

When you hand work to an AI employee, block forbidden actions with mechanisms, not instructions. The official documentation explains that permission rules are enforced by Claude Code, not by the model. Instructions in CLAUDE.md or prompts only shape what Claude tries to do; they do not change what is allowed.

Permission Settings

There are three kinds of permission rules: allow (use without asking), ask (confirm every time) and deny (cannot use). Rules are checked in the order deny, ask, allow, and the first match decides the result. A broad deny rule blocks an action even if a more specific allow rule exists. Use /permissions to review and change the rules.

The order in which permission rules are checked

1Does it match deny?If so, it cannot be used
2Does it match ask?If so, confirm first
3Does it match allow?If so, use it without asking

Hooks

Hooks are shell commands that run automatically at set points in Claude Code. They always run, regardless of what the AI chooses. For example, a PreToolUse hook runs before a tool is used and can block that action. If it exits with code 2, the action is blocked.

When a PreToolUse hook returns a denial, the action is blocked even if you run Claude Code in a mode that skips permission prompts. The official documentation includes an example that blocks edits to protected files. For AI employees that touch customer data or production environments, put this mechanism in place first.

Letting Others Use the AI Employees You Build

There are several ways to let other people or companies use the AI employees you build.

Share them in the project: commit CLAUDE.md, .claude/agents/ and .claude/skills/ to the repository
Package them as a plugin: others can install skills, subagents, hooks and MCP servers as one bundle. The configuration goes in .claude-plugin/plugin.json
Run them from the command line: claude -p runs a single task without an interactive session
Build them into your own app: with the Claude Agent SDK, use the same tools and agent loop from Python or TypeScript

If you build a product for other companies with the Claude Agent SDK, check the conditions. The official documentation does not allow third-party developers to offer claude.ai login or usage limits in their products unless previously approved. Use API key authentication instead. It also does not allow using the Claude Code name or a look that imitates it in your product. We compare other frameworks in AI Agent Frameworks.

Employee Store is a marketplace where companies can adopt AI agents built by developers, through a one-time purchase or a monthly plan. Any format is accepted, including custom-built agents that use the Claude API. There is no listing fee or upfront cost. The fee is 20% of the deal amount and applies only when a deal closes.

FAQ

Are prohibitions written in CLAUDE.md always followed?: Not always. The official documentation explains that CLAUDE.md is read as context, not as an enforced setting. Block actions that must never happen with deny rules in the permission settings or with a PreToolUse hook.
When should I use a subagent and when a skill?: Use a subagent when you want work done in a separate context and only a summary of the results returned. Use a skill when you want to reuse set procedures or instructions within the main conversation.
Do subagents increase usage?: Subagents send their own requests, and these count toward the same usage limits as the main conversation. To keep costs down, the official documentation also suggests delegating tasks to subagents that use a faster, lower-cost model such as Haiku.

About the author

Employee Store OperationsThe operations team behind Employee Store, a marketplace for AI agents. We check tool features and pricing against official sources and list them at the end of each article. If you spot an error, please let us know via the contact form.

Building AI Employees with Claude Code: Subagents and Settings

Summary

What Building an AI Employee with Claude Code Means