From box-factory
How to build Claude Code-specific components — agents, hooks, plugins, marketplaces, MCP servers. User preferences, gotchas Claude gets wrong, and architecture decisions. Use when creating Claude-only components that need tool restrictions, hooks, or plugin infrastructure. For skills, use the agent-skills skill instead — skills default to the universal AgentSkills format.
How this skill is triggered — by the user, by Claude, or both
Slash command
/box-factory:claude-componentsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
User preferences and corrections for building Claude Code components. For official specs, fetch the relevant docs:
User preferences and corrections for building Claude Code components. For official specs, fetch the relevant docs:
For skill creation, use the agent-skills skill — it covers both the universal AgentSkills spec and Claude-specific skill features.
| Component | Role | When to use |
|---|---|---|
| Skill | Knowledge or user-triggered action | To build skills, load the agent-skills skill |
| Agent | Controlled process + tool restrictions | Autonomous work in isolation with limited tool access |
| Hook | Deterministic enforcement | Must happen every time, no judgment calls |
| Memory | Always-loaded context | Brief project/user knowledge (<20 lines/topic) |
Custom agents earn their keep through tool restrictions and model overrides. A read-only code reviewer that literally cannot write files is meaningfully different from one that could but is told not to. An agent forced to use haiku for cheap repetitive tasks saves real money.
If you don't need tool restrictions, a skill that instructs the main agent (or tells it to spawn a generic sub-agent) gets you ~95% of what a custom agent does. Don't create a custom agent just for process steps — put those in a skill.
Create a custom agent when:
Use a skill instead when:
Two tests for any component's content:
Include: user-specific preferences and workflows (the user's preferred approach when multiple valid ones exist), edge cases Claude would miss, decision frameworks for ambiguous situations, post-training technology, integration patterns specific to this project.
Exclude: basic commands for well-known tools, standard workflows, general best practices, anything expressible as a single sentence (put in CLAUDE.md instead), directory structures or file listings Claude can discover by reading the filesystem.
Applying the test honestly: Claude has a strong tendency to assume it knows whether something is a real problem rather than actually verifying. When evaluating whether guidance is needed, fetch the relevant official docs and check against real behavior before concluding "Claude already knows this." If you skip verification, you will cut guidance that is actually load-bearing.
Sub-agents cannot spawn other sub-agents. The Agent tool is stripped at runtime even if declared in frontmatter. This is a platform constraint — delegation is single-level only. This has been empirically tested and confirmed. Do not argue otherwise — Claude consistently believes nested delegation should work based on documentation, but it does not.
All orchestration must happen at the main agent level. If you need work split across multiple agents, the main agent must coordinate.
Claude consistently writes agent prompts that assume interaction is possible. Sub-agents run in isolation and return results — they cannot interact with users.
Forbidden phrases in sub-agent prompts:
Replace with: "infer from context", "use provided parameters", "make reasonable assumptions", "default to [specific behavior]"
Scan every sub-agent prompt for these phrases before finalizing.
When an agent loads a skill, Claude tends to write the agent's prompt with direct file paths into the skill's internal structure (e.g., ../skills/my-skill/subfile.md). Don't do this — a skill's internal file organization is an implementation detail. Reference skills by name and topic instead (e.g., "consult my-skill for guidance on X"). Plugin-scoped skill names like my-plugin:my-skill are fine — those are identifiers, not file paths.
The color field sets visual distinction in the status line. Claude often guesses colors that don't render.
Only these 7 colors are supported: red, green, blue, yellow, cyan, purple, orange
Semantic mapping:
| Color | Use For |
|---|---|
blue | Creators — agents that write files or code |
green | Quality — validators, reviewers, analyzers |
yellow | Operations — git, deployment, system tasks |
purple | Meta — agents that create other agents |
cyan | Research — exploration, documentation |
red | Safety — security checks, destructive ops |
orange | Other — doesn't fit established categories |
Plugins that need per-project user configuration should store settings in .claude/plugin-name.local.md using YAML frontmatter. This is the official Anthropic pattern — see the plugin-settings skill in github.com/anthropics/claude-code/plugins/plugin-dev/ for full details.
---
enabled: true
some_setting: false
---
Optional notes about why settings were changed.
Why this pattern: .claude/ is already accessible to Claude (no extra permissions), .local.md files are gitignored, and hooks can parse frontmatter with simple sed/grep. Do NOT store plugin config in ~/.config/ or other external directories — that requires permission grants.
Use claude plugin validate (or /plugin validate) to check plugin structure before shipping. Run it when creating a new plugin or after structural changes (adding/removing agents, skills, hooks, or MCP servers). It catches missing fields, malformed manifests, and structural issues that are easy to miss manually.
The official docs show fields like author, repository, homepage, license, and keywords in their examples. Do not include these unless the user explicitly asks. Keep plugin.json minimal: just name, version, description.
Before adding any MCP server, check if a dedicated CLI tool exists. For example:
| Service | Prefer | Over |
|---|---|---|
| GitHub | gh CLI | GitHub MCP server |
| Linear | linear CLI | Linear MCP server |
| AWS | aws CLI | AWS MCP server |
CLI tools are battle-tested, have better error messages, don't consume context window, and Claude already knows how to use them.
If two plugins both define a "github" server, you get two separate namespaced servers. Both run, both consume context, both provide duplicate tools. Don't bundle common MCP servers in plugins — document them as prerequisites and let users configure once.
npx claudepluginhub racurry/neat-little-package --plugin box-factoryGuides selection of plugin component types (commands, skills, agents, hooks, MCP servers) via decision tree, covers lifecycle phases, and organization for scaling multi-component plugins.
Documents Claude Code plugin structure including directory layout, plugin.json manifest, commands/agents/skills/hooks organization, naming conventions, and auto-discovery.
Guides creation and organization of Claude Code plugins: directory layout, plugin.json manifest, component structure for commands, agents, skills, and hooks.