custom-agent-definitions
Write and configure custom agent definitions in Claude Code agents/ directory. Use when creating an agent .md file, defining a specialized agent, or configuring agent tools.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill custom-agent-definitionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a documentation resource that teaches how to define and configure custom agents. It contains no malicious code, remote dependencies, or data exfiltration patterns, and it actively promotes security best practices such as context isolation and the principle of least privilege.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Custom Agent Definitions
Expert knowledge for defining and configuring custom agents in Claude Code.
For full worked YAML examples (isolated research agent, read-only explorer, complete security auditor, plugin layout, common patterns), see REFERENCE.md.
When to Use This Skill
| Use this skill when... | Use agent-teams instead when... |
|---|---|
Authoring a new .md agent definition file in .claude/agents/ | Spawning multiple already-defined agents that coordinate as a team |
Configuring a single agent's model, allowed-tools, or context: fork | Setting up a lead/teammate architecture with a shared task list |
| Constraining tool access for a specialised read-only or write-restricted agent | Sequencing parallel work across worktrees (see parallel-agent-dispatch) |
| Writing the system prompt that defines what one agent does | Auditing existing agent definitions for security (see meta-audit) |
Core Concepts
Custom agents let you define specialized agent types beyond the built-in
ones (Explore, Plan, Bash, etc.). Each can have its own model, tools, and
context configuration. They are defined in .claude/agents/ or via plugin
agents/ directories, with YAML frontmatter + a markdown system prompt:
---
name: my-custom-agent
description: What this agent does
model: sonnet
allowed-tools: Bash, Read, Grep, Glob
---
# Agent System Prompt
Instructions and context for the agent...
Key Fields
Context Forking
| Value | Behavior |
|---|---|
fork | Independent context copy — agent sees parent history but changes don't affect parent |
| (default) | Agent shares context with parent and can see/modify conversation state |
Use fork for exploratory research, parallel investigations, and isolated
experiments. See REFERENCE.md → Isolated research agent.
Tool Access (allowed vs disallowed)
| Field | Purpose | Behavior |
|---|---|---|
allowed-tools | Whitelist of permitted tools | Agent can ONLY use these tools |
disallowedTools | Blacklist of forbidden tools | Agent can use all tools EXCEPT these |
Use disallowedTools for read-only agents, restricting dangerous capabilities,
and sandboxing. The two combine — an explicit whitelist plus a safety blacklist.
See REFERENCE.md → Read-only explorer.
Agent Field for Delegation
The agent field specifies which agent type to use when delegating via the Agent
tool, letting commands and skills name a preferred agent type:
agent: security-auditor
Agent Configuration Fields Reference
| Field | Type | Description |
|---|---|---|
name | string | Agent identifier |
description | string | What the agent does |
model | string | Model to use (sonnet, opus) |
context | string | Context mode: fork or default |
permissionMode | string | default, acceptEdits, dontAsk, bypassPermissions, or plan |
maxTurns | number | Maximum agentic turns before agent stops |
background | bool | Set true to always run as a background task |
memory | string | Persistent memory scope: user, project, or local |
skills | list | Skill names to preload into agent context at startup |
mcpServers | list | MCP server names available to this agent |
tools | list | Tools the agent can use (in agents/ dir; use allowed-tools in skills) |
disallowedTools | list | Tools the agent cannot use |
created / modified / reviewed | date | Lifecycle dates |
Best Practices
-
Principle of least privilege — grant only the tools the agent needs.
-
Use
context: forkfor isolation — exploratory work shouldn't pollute main context. -
Combine allowed + disallowed — explicit whitelist with a safety blacklist.
-
Clear descriptions — describe what the agent does and its boundaries.
-
Model selection —
sonnetfor development workflows,opusfor deep reasoning/analysis. (See.claude/rules/agent-and-tool-selection.mdfor the repo's Opus-for-subagents guidance.) -
Report failures loudly — a dispatched agent that hits a wall must say so in its final message, never a one-word summary like
Terminal./Done./Stopped.On a blocker it should commit and push its in-progress work, open a draft PR, and state exactly what stopped it and which tools were denied. A one-word surrender is indistinguishable from success to the orchestrator, so the work is silently cleaned up and lost (issue #1422). Seeparallel-agent-dispatch→ "Loud-failure contract" for the dispatch-prompt form every brief should carry. -
Prefer a Skill-less agentType for read-only fan-out — an agent that only reads files and emits structured output should NOT carry the
Skilltool. EverySkill-bearing agent pays a ~25k-tokenskill_listing+deferred_tools_deltacontext tax before its first tool call, which can push read-heavy fan-out subagents over their context window. Use a lean read-only agent (e.g.agents-plugin:review) instead. Seeparallel-agent-dispatch→ "Skill-less agentType for Read-Only Fan-Out" (issues #1549 / #1550).
Worked YAML for each practice is in REFERENCE.md → Best-practice snippets.
Quick Reference
Context Modes
| Mode | Isolation | Use Case |
|---|---|---|
| (default) | Shared | Normal workflows |
fork | Isolated | Research, experiments |
Tool Restriction Patterns
| Pattern | Fields |
|---|---|
| Whitelist only | allowed-tools: Tool1, Tool2 |
| Blacklist only | disallowedTools: Tool1, Tool2 |
| Combined | Both fields specified |
Related
- REFERENCE.md — full worked YAML examples and snippets
agent-teams— multi-agent coordination via the implicit teamparallel-agent-dispatch— worktree preflight, scope budgets, loud-failure contractmeta-audit— auditing existing agent definitions for security/completeness.claude/rules/agent-development.md— agent lifecycle and field semantics
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/custom-agent-definitions">View custom-agent-definitions on skillZs</a>