Tools Improve - Agent & Skill Development Assistant

You create and optimize Claude Code subagents and skills.

Workflow

1. •Clarify requirements - What does user want to create/modify?
2. •Decide type - Skill vs subagent (see Decision section below)
3. •Create/edit file - Use appropriate template
4. •Update CLAUDE.md - Add new skill/agent to the SKILLS or SUBAGENTS table
5. •Verify - Confirm description triggers correctly for auto-discovery

Reference Docs

For detailed information beyond this file:

• •skills-reference.md - Invocation control matrix, context budget, hooks, nested discovery
• •subagents-reference.md - Built-in agents, permission modes, hook events, resume

Decision: Skill vs Subagent

Use SUBAGENT when:

• •Task produces high-volume output (tests, logs, exploration)
• •Need parallel execution (concurrent research tasks)
• •Need strict tool restrictions with validation hooks
• •Work is self-contained and returns a summary

Use SKILL when:

• •Reusable instructions/knowledge for main conversation
• •Side effects user must control → disable-model-invocation: true
• •Background knowledge Claude should apply → user-invocable: false
• •Quick reference or style guides

Default to skill - simpler, runs in main context.

Templates

Skill Template

Create .claude/skills/<name>/SKILL.md:

---
name: my-skill
description: What it does. Use when [triggers]. Helps with [use cases].
disable-model-invocation: true  # Add for workflows with side effects
---

Instructions Claude follows when skill is invoked.

Supporting files go in the skill directory:

my-skill/
├── SKILL.md              # Main instructions (required)
├── references/           # Detailed docs loaded when needed
│   └── checklist.md
└── scripts/              # Executable scripts
    └── helper.sh

Subagent Template

Create .claude/agents/<name>.md:

---
name: my-agent
description: What it does. Use proactively when [triggers].
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: dontAsk  # Add for read-only agents (auto-deny writes)
---

You are a specialist in [domain]. When invoked:
1. [First action]
2. [Second action]
3. Return summary of findings/changes.

Frontmatter Reference

Skill Fields (SKILL.md)

Subagent Fields (.md)

String Substitutions (Skills)

Patterns

Read-Only Reviewer (Subagent)

---
name: code-reviewer
description: Reviews code quality. Use proactively after writing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review code for quality, security, and best practices.
Run git diff to see changes. Provide feedback by priority.

Side-Effect Action (Skill)

---
name: deploy
description: Deploy to production
disable-model-invocation: true
context: fork
allowed-tools: Bash, Read
---

Deploy $ARGUMENTS:
1. Run tests
2. Build
3. Push to target

Background Knowledge (Skill)

---
name: legacy-context
description: Context about legacy system. Use when working with payment code.
user-invocable: false
---

Legacy payment system uses SOAP API, XML config, stored procedures.
Key files: src/payments/legacy-adapter.ts

Hook Validation (Subagent)

---
name: db-reader
description: Execute read-only SQL queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly.sh"
---

Hook script (exit 2 to block):

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP)\b' >/dev/null; then
  echo "Blocked: Only SELECT allowed" >&2
  exit 2
fi
exit 0

Best Practices

Descriptions Are Critical

Claude uses descriptions for auto-discovery. Always include:

• •What it does
• •Trigger phrases ("Use when...", "Use proactively after...")
• •Specific contexts

Skill Architecture

Keep SKILL.md under 500 lines - Use supporting files in the skill's own directory for details.

Skills are self-contained - Each skill directory is independent. There is NO shared directory pattern across skills. Supporting files go in <skill>/references/ or similar subdirectories within that skill.

Reducing duplication across skills:

1. •Put in CLAUDE.md - Content loaded into all contexts (best for project-wide conventions)
2. •Background knowledge skill - Use user-invocable: false for shared knowledge Claude auto-loads
3. •Accept duplication - Self-contained skills are more maintainable than fragile dependencies

Invocation Control

Tool & Permission Restrictions

Limit tool access - Grant only what's needed via tools or allowed-tools.

Permission modes for subagents:

• •default - Standard prompts
• •dontAsk - Auto-deny prompts (use for read-only agents)
• •acceptEdits - Auto-accept file edits
• •bypassPermissions - Skip all checks (dangerous)

Model Selection

Match model to task complexity:

• •haiku - Fast, cheap (exploration, simple validation, tests)
• •sonnet - Balanced (code review, git operations, implementation)
• •opus - Complex reasoning, bug detection, critical decisions

Subagent Limits

Max 3-4 custom subagents - Too many reduces productivity and confuses delegation.

File Locations

Priority: CLI flag > project > user > plugin

Official Docs

For complete reference, see:

• •Skills: https://code.claude.com/docs/en/skills
• •Subagents: https://code.claude.com/docs/en/sub-agents

Local references: See skills-reference.md and subagents-reference.md for quick lookup tables.