---
name: majiayu000/custom-agent
source: https://app.decimal.ai/s/majiayu000-custom-agent@1/SKILL.md
source_sha256: b7bd5abcf277
---

> **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI may ask user whether to skip.

## Quick Summary

**Goal:** Create new custom agents, audit existing agent quality, or enhance agent definitions.

**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`

## 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** — `AskUserQuestion`: 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. **Parse** — Read first 30 lines of each, extract frontmatter
3. **Validate** — Check each audit rule below
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

```yaml
---
# 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 — Limits
maxTurns: 30                      # Prevents runaway agents

# 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 (gitignored)

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

## Tool Restriction Patterns

| Agent Type | Recommended `tools` |
|---|---|
| Explorer/Scout | `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, TaskCreate, TaskUpdate, AskUserQuestion, + MCP tools.

## Model Selection

| Model | Best For |
|---|---|
| `haiku` | Fast read-only: scanning, search, file listing |
| `sonnet` | Balanced: code review, debugging, analysis |
| `opus` | High-stakes: architecture, complex implementation |
| `inherit` | Default — match parent's model |

## Description Best Practices

```yaml
# 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 |
| No `maxTurns` | Set 20-30 to prevent runaway |
| 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 |
| 9 | maxTurns set | Recommended 20-30 | Info |

**Quality Score:** Valid frontmatter (20) + Description >50 chars (20) + Tools restricted (15) + Role section (15) + Workflow section (10) + Model set (10) + maxTurns set (10) = 100. 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

<user-prompt>$ARGUMENTS</user-prompt>

---

**IMPORTANT Task Planning Notes (MUST FOLLOW)**

- Always break work into small todo tasks
- Always add a final review todo task