SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscustom-agent

custom-agent

Agents & models

View repository

Updated 11-06 09:09

About this skill

Codex compatibility note:

  • Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author .claude/**; mirrors are generated.
  • Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
  • Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
  • Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
  • Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

Quick Summary

Goal: Create new custom agents, audit existing agent quality, or enhance agent definitions so each agent is valid, least-privilege, structurally complete, and ready for safe delegation.

Summary: Produce valid agents through the selected mode: Create — clarify → check existing → scaffold → write → validate; Audit — discover → read/parse → validate → report → fix confirmed Errors; Enhance — read → analyze → recommend → apply confirmed changes. Validate frontmatter, tools, structure, and quality score.

Workflow: Detect mode (Create/Audit/Enhance) from $ARGUMENTS → Execute → Validate

Key Rules:

  • Agent files: .claude/agents/{name}.md with YAML frontmatter + markdown body as system prompt
  • Agent does NOT inherit Claude Code system prompt — write complete instructions
  • Minimize tools to only what the agent needs
  • System prompt structure: ## Role → ## Workflow → ## Key Rules → ## Output
  • Analyze scope and use todo tracking for small tasks/subtasks before starting, including final review. Keep task depth proportional to the work.

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Contents

  • Quick Summary
  • Modes
  • Mode 1: Create Agent
  • Mode 2: Audit Agents
  • Mode 3: Enhance Agent
  • Agent Frontmatter Schema
  • Tool Restriction Patterns
  • Model Selection
  • Description Best Practices
  • Common Anti-Patterns
  • Context Passing
  • Audit Checklist
  • File Priority (highest first)
  • Requirements
  • Closing Reminders

Modes

Mode Trigger Action
Create $ARGUMENTS describes a new agent Create agent file
Audit mentions verify, audit, review, check, quality Audit existing agents
Enhance mentions refactor, enhance, improve, optimize Improve existing agent

Mode 1: Create Agent

  1. Clarify — ask user question tool: purpose, read-only vs read-write, model preference, memory needs
  2. Check Existing — Glob .claude/agents/*.md for similar agents. Avoid duplication.
  3. Scaffold — Create .claude/agents/{name}.md using frontmatter template below
  4. Write System Prompt — Structure: ## Role → ## Workflow → ## Key Rules → ## Output
  5. Validate — Run audit checklist below

Mode 2: Audit Agents

  1. Discover — Glob .claude/agents/*.md
  2. Read and parse — Read each complete frontmatter and body before checking or scoring it. A header preview is discovery only; follow multiline YAML through its closing delimiter.
  3. Validate — Apply the Audit Checklist and quality score; consult Agent Frontmatter Schema for field definitions and Tool Restriction Patterns for tool scope.
  4. Report — Issues grouped by severity (Error > Warning > Info), include quality scores
  5. Fix — If user confirms, fix Error-level issues automatically

Mode 3: Enhance Agent

  1. Read — Load specified agent file
  2. Analyze — Check against best practices and audit checklist
  3. Recommend — List improvements with rationale
  4. Apply — If user confirms, apply enhancements

Agent Frontmatter Schema

---
# REQUIRED
name: my-agent # Lowercase + hyphens only
description: >- # Claude uses this to decide when to delegate
    Use this agent when [specific trigger scenarios].

# OPTIONAL — Tools
tools: Read, Grep, Glob, Bash # Allowlist (omit both → inherits all)
disallowedTools: Write, Edit # Denylist (removes from inherited set)
# Task(agent1, agent2) restricts spawnable subagents

# OPTIONAL — Model
model: inherit # inherit | sonnet | opus | haiku

# OPTIONAL — Permissions
permissionMode: default # default | acceptEdits | dontAsk | bypassPermissions | plan

# OPTIONAL — Skills (content injected at startup)
skills:
    - skill-name

# OPTIONAL — MCP Servers
mcpServers:
    - server-name

# OPTIONAL — Hooks (scoped to this agent)
hooks:
    PreToolUse:
        - matcher: 'Bash'
          hooks:
              - type: command
                command: './scripts/validate.sh'

# OPTIONAL — Memory (MEMORY.md auto-injected, Read/Write/Edit auto-added)
memory: project # user (~/.claude/agent-memory/) | project (.claude/agent-memory/) | local (.claude/agent-memory-local/); .claude/.gitignore ignores both project folders

# OPTIONAL — Execution
background: false # true = always background task
isolation: worktree # Run in temporary git worktree
---

Tool Restriction Patterns

Agent Type Recommended tools
Explorer / $investigate Read, Grep, Glob, Bash
Reviewer (read-only) Read, Grep, Glob
Writer/Implementer Read, Write, Edit, Grep, Glob, Bash
Researcher Read, Grep, Glob, WebFetch, WebSearch
Orchestrator Read, Grep, Glob, Task(sub1, sub2)

Available tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, WebFetch, WebSearch, Task, NotebookRead, NotebookEdit, todo tracking, TaskUpdate, ask user question tool, + MCP tools.

Model Selection

These are routing heuristics, not measured quality rankings or compatibility evidence. Preserve an explicit user choice; otherwise prefer inherit. Record representative model/runtime tests separately, with unavailable comparisons marked NOT RUN.

Model Best For
haiku Fast read-only: scanning, search, file listing
sonnet Balanced: code review, debugging, analysis
opus Candidate for high-stakes architecture or complex implementation; verify suitability on representative tasks
inherit Default — match parent's model

Description Best Practices

# BAD — too vague, Claude won't auto-delegate
description: Reviews code

# GOOD — specific trigger conditions
description: >-
  Use this agent for comprehensive code review after implementing features,
  before merging PRs, or when assessing code quality and technical debt.
  • Include "Use this agent when..." phrasing with concrete scenarios
  • Add "use proactively" to encourage auto-invocation

Common Anti-Patterns

Anti-Pattern Fix
No tool restrictions Add tools allowlist
Vague description Write specific trigger conditions
Giant system prompt Keep concise, use skills for detail
Recursive subagents Restrict Task in tools
Windows long prompts (>8191 chars) Use file-based agents, not --agents CLI

Context Passing

  • Agent receives ONLY its system prompt + task prompt — NOT parent conversation
  • Parent receives ONLY agent's final result — NOT intermediate tool calls
  • This isolation is the primary context management benefit

Audit Checklist

# Check Rule Severity
1 Frontmatter exists Must have --- delimiters Error
2 Name present & valid Lowercase + hyphens only Error
3 Description present Non-empty, >20 chars Error
4 No duplicate names Unique across all agent files Error
5 Description quality Specific trigger scenarios Warning
6 Tools minimal Only what agent needs Warning
7 Prompt structure Has ## Role + ## Workflow Warning
8 Model set When task differs from default Info

Quality Score: Valid frontmatter (20) + Description >50 chars (20) + Tools restricted (15) + Role section (15) + Workflow section (10) + Model set (10) = 90. Rating: 80+ Excellent, 60-79 Good, 40-59 Needs Work, <40 Poor.

File Priority (highest first)

  1. --agents CLI flag (session only)
  2. .claude/agents/*.md (project)
  3. ~/.claude/agents/*.md (user)
  4. Plugin agents/ directory

Same name across levels: higher-priority wins. Use claude agents CLI to list all.

Requirements

$ARGUMENTS

Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

  • review-decision-autonomy — Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.md

MUST ATTENTION Decide supported review choices and recommendations, record the rationale, and finish without routine user questions. Keep round-limit extension, indispensable facts and actual action authority; preserve source coverage, validation, tests, read-only boundaries and budgets. Review decisions do not accept open risks or make a failed gate pass.

Closing Reminders

IMPORTANT MUST ATTENTION Goal: Create new custom agents, audit existing agent quality, or enhance agent definitions so each agent is valid, least-privilege, structurally complete, and ready for safe delegation.

IMPORTANT MUST ATTENTION follow the mode-specific path: detect mode → Create: clarify, check existing agents, scaffold, write the system prompt, validate; Audit: discover, parse, validate, report, and fix only after confirmation; Enhance: read, analyze, recommend, apply only after confirmation; then run the final audit checklist and quality-score validation.

Protocols in force (concise digest of the SYNC/shared blocks this skill carries):

  • AI Mistakes: holistic-first debug, fix at responsible layer, surgical diff, verify ALL outputs.

  • Use todo tracking before starting, including final review; keep task depth proportional to the work.

  • Search 3+ similar patterns before creating code; cite file:line for every claim, with confidence >80% to act.

Evasion Required action
"Header preview is enough" Read complete frontmatter and body before checking or scoring
"Audit found Errors, fix now" Report first; fix Error-level issues only after user confirmation