AgentSkillsCN

subagent-tweaker

修复、优化或更新现有的 Claude Code 自定义代理（子代理）。当用户：(1) 反映某项代理运行不佳；(2) 希望调整代理的行为、工具或模型；(3) 提出“修复代理”、“更新代理”、“微调代理”、“代理无法正常工作”时，可使用此技能。内容包括：编辑代理 frontmatter，调整工具限制，更新提示词，排查问题。

SKILL.md
--- frontmatter
name: subagent-tweaker
description: >
  Fix, improve, or update existing Claude Code custom agents (subagents). Use when: (1) User reports
  an agent isn't working well, (2) User wants to adjust agent behavior, tools, or model, (3) User
  says 'fix agent', 'update agent', 'tweak agent', 'agent not working'. Handles: editing agent
  frontmatter, adjusting tool restrictions, updating prompts, debugging issues.

Tweak Custom Agent

Workflow

Step 1: Identify the agent

Find agents at:

  • •~/.claude/agents/*.md (personal)
  • •.claude/agents/*.md (project)

Read the agent file to understand current configuration.

Step 2: Diagnose the issue

Common problems and fixes:

ProblemLikely CauseFix
Agent not being usedPoor descriptionRewrite with clear trigger keywords
Agent too slowWrong modelSwitch to sonnet or haiku
Agent can't edit filestools missing Write/EditAdd needed tools to allowlist
Agent doing too muchNo tool restrictionsAdd tools: or disallowedTools:
Agent forgets contextNo persistent memoryAdd memory: user or memory: project
Agent runs too longNo turn limitAdd maxTurns: N

Step 3: Apply changes

Edit the agent's Markdown file. Preserve existing content that works well.

Frontmatter fields reference:

FieldDescription
nameIdentifier (lowercase, hyphens)
descriptionWhen to use (Claude reads this for delegation)
modelopus, sonnet, haiku, inherit
toolsTool allowlist (inherits all if omitted)
disallowedToolsTool denylist
permissionModedefault, acceptEdits, delegate, dontAsk, bypassPermissions, plan
maxTurnsMax agentic turns
skillsPreloaded skills
mcpServersAvailable MCP servers
hooksScoped lifecycle hooks
memoryuser, project, local

Step 4: Verify

After editing:

  1. •Confirm YAML frontmatter has no syntax errors
  2. •Check tool restrictions match intended behavior
  3. •Verify description contains keywords users would say

Tips

  • •Keep agent body (system prompt) focused and concise
  • •Subagents cannot nest - don't add Task tool to agents that will be spawned as subagents
  • •When adjusting tools, prefer disallowedTools over tools if only blocking a few
  • •description is the primary trigger mechanism - this is the most impactful field to improve