skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
laurigates/claude-plugins65 installs

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-definitions
view source ↗

Is 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: forkSetting up a lead/teammate architecture with a shared task list
Constraining tool access for a specialised read-only or write-restricted agentSequencing parallel work across worktrees (see parallel-agent-dispatch)
Writing the system prompt that defines what one agent doesAuditing 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

ValueBehavior
forkIndependent 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)

FieldPurposeBehavior
allowed-toolsWhitelist of permitted toolsAgent can ONLY use these tools
disallowedToolsBlacklist of forbidden toolsAgent 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

FieldTypeDescription
namestringAgent identifier
descriptionstringWhat the agent does
modelstringModel to use (sonnet, opus)
contextstringContext mode: fork or default
permissionModestringdefault, acceptEdits, dontAsk, bypassPermissions, or plan
maxTurnsnumberMaximum agentic turns before agent stops
backgroundboolSet true to always run as a background task
memorystringPersistent memory scope: user, project, or local
skillslistSkill names to preload into agent context at startup
mcpServerslistMCP server names available to this agent
toolslistTools the agent can use (in agents/ dir; use allowed-tools in skills)
disallowedToolslistTools the agent cannot use
created / modified / revieweddateLifecycle dates

Best Practices

  1. Principle of least privilege — grant only the tools the agent needs.

  2. Use context: fork for isolation — exploratory work shouldn't pollute main context.

  3. Combine allowed + disallowed — explicit whitelist with a safety blacklist.

  4. Clear descriptions — describe what the agent does and its boundaries.

  5. Model selection — sonnet for development workflows, opus for deep reasoning/analysis. (See .claude/rules/agent-and-tool-selection.md for the repo's Opus-for-subagents guidance.)

  6. 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). See parallel-agent-dispatch → "Loud-failure contract" for the dispatch-prompt form every brief should carry.

  7. Prefer a Skill-less agentType for read-only fan-out — an agent that only reads files and emits structured output should NOT carry the Skill tool. Every Skill-bearing agent pays a ~25k-token skill_listing + deferred_tools_delta context 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. See parallel-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

ModeIsolationUse Case
(default)SharedNormal workflows
forkIsolatedResearch, experiments

Tool Restriction Patterns

PatternFields
Whitelist onlyallowed-tools: Tool1, Tool2
Blacklist onlydisallowedTools: Tool1, Tool2
CombinedBoth fields specified

Related

  • REFERENCE.md — full worked YAML examples and snippets
  • agent-teams — multi-agent coordination via the implicit team
  • parallel-agent-dispatch — worktree preflight, scope budgets, loud-failure contract
  • meta-audit — auditing existing agent definitions for security/completeness
  • .claude/rules/agent-development.md — agent lifecycle and field semantics

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>