How do I install the Subagent Tweaker skill?

Run npx skillmds@latest add takazudo/subagent-tweaker in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Subagent Tweaker safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Subagent Tweaker?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Subagent Tweaker free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Subagent Tweaker?

takazudo (@takazudo) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Subagent Tweaker by takazudo — Agent Skill

Name: Subagent Tweaker
Author: takazudo

Subagent Tweaker

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'. Edits agent frontmatter, tool restrictions, prompts.

takazudo 4273274 2.6 KB Updated Sep 17, 2026

File contents

Tweak Custom Agent

Workflow

Step 1: Identify the agent

Find agents at:

$HOME/.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:

Problem	Likely Cause	Fix
Agent not being used	Poor `description`	Rewrite with clear trigger keywords
Agent too slow	Wrong `model`	Switch to `sonnet` or `haiku`
Agent can't edit files	`tools` missing Write/Edit	Add needed tools to allowlist
Agent doing too much	No tool restrictions	Add `tools:` or `disallowedTools:`
Agent forgets context	No persistent memory	Add `memory: user` or `memory: project`
Agent runs too long	No turn limit	Add `maxTurns: N`

Step 3: Apply changes

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

Frontmatter fields reference:

Field	Description
`name`	Identifier (lowercase, hyphens)
`description`	When to use (Claude reads this for delegation)
`model`	`opus`, `sonnet`, `haiku`, `inherit`
`tools`	Tool allowlist (inherits all if omitted)
`disallowedTools`	Tool denylist
`permissionMode`	`default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, `plan`
`maxTurns`	Max agentic turns
`skills`	Preloaded skills
`mcpServers`	Available MCP servers
`hooks`	Scoped lifecycle hooks
`memory`	`user`, `project`, `local`

Step 4: Format the agent file

Format the edited agent file using the mdx-formatter to ensure consistent markdown formatting:

pnpm dlx @takazudo/mdx-formatter --write <path-to-agent-file.md>

Step 5: Verify

After editing:

Confirm YAML frontmatter has no syntax errors
Check tool restrictions match intended behavior
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

---name: subagent-tweakerdescription: 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'. Edits agent frontmatter, tool restrictions, prompts.---# Tweak Custom Agent## Workflow### Step 1: Identify the agentFind agents at:- `$HOME/.claude/agents/*.md` (personal)- `.claude/agents/*.md` (project)Read the agent file to understand current configuration.### Step 2: Diagnose the issueCommon problems and fixes:| Problem | Likely Cause | Fix ||---------|-------------|-----|| Agent not being used | Poor `description` | Rewrite with clear trigger keywords || Agent too slow | Wrong `model` | Switch to `sonnet` or `haiku` || Agent can't edit files | `tools` missing Write/Edit | Add needed tools to allowlist || Agent doing too much | No tool restrictions | Add `tools:` or `disallowedTools:` || Agent forgets context | No persistent memory | Add `memory: user` or `memory: project` || Agent runs too long | No turn limit | Add `maxTurns: N` |### Step 3: Apply changesEdit the agent's Markdown file. Preserve existing content that works well.**Frontmatter fields reference:**| Field | Description ||-------|-------------|| `name` | Identifier (lowercase, hyphens) || `description` | When to use (Claude reads this for delegation) || `model` | `opus`, `sonnet`, `haiku`, `inherit` || `tools` | Tool allowlist (inherits all if omitted) || `disallowedTools` | Tool denylist || `permissionMode` | `default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, `plan` || `maxTurns` | Max agentic turns || `skills` | Preloaded skills || `mcpServers` | Available MCP servers || `hooks` | Scoped lifecycle hooks || `memory` | `user`, `project`, `local` |### Step 4: Format the agent fileFormat the edited agent file using the mdx-formatter to ensure consistent markdown formatting:```bashpnpm dlx @takazudo/mdx-formatter --write <path-to-agent-file.md>```### Step 5: VerifyAfter editing:1. Confirm YAML frontmatter has no syntax errors2. Check tool restrictions match intended behavior3. 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

Frequently asked questions