Imported from r-senchuk/agentskills (.agents/skills/agent-builder/SKILL.md). Install upstream with npx skills add r-senchuk/agentskills --skill agent-builder. Copyright stays with the author.

Agent Builder

When To Use

• Create: Designing a new .agent.md for a specialized workflow, subagent role, or tool-restricted persona.
• Improve: Auditing an existing agent for vague description, Swiss-army tool list, missing constraints, or weak persona.
• Orchestration design: Planning a multi-agent system where one agent delegates to others.

Do NOT use for general coding tasks. Use when the output is an .agent.md file.

Inputs To Collect First

1. Agent name (kebab-case, maps to <name>.agent.md)
2. Purpose — one sentence: what job does this agent do that the default agent cannot?
3. Invocability — user-facing picker agent or behind-the-scenes subagent (user-invocable: true/false)?
4. Tool requirements — what operations must it perform? (read, edit, execute, web, search, agent)
5. Skills to assign — which SKILL.md skills does this agent rely on?
6. Location — workspace (.github/agents/) or user profile?

Procedure

Step 1 — Define Agent Scope

Answer these before writing anything:

• Single role: What is the ONE thing this agent is best at?
• Exclusions: What should it never do? (prevents scope creep)
• Delegation: Which tasks should it hand off to subagents or invoke via skills?
• Output: What exactly does it return to the caller?

If the scope is unclear, narrow it — broad agents underperform specialists.

Step 2 — Identify Required Skills

List the skills this agent needs. For each skill:

1. Check if it already exists: ls .agents/skills/
2. If missing, create it first using the skill-builder skill before proceeding
3. Document the trigger condition that tells the agent when to load each skill

Dependency rule: Never write the .agent.md until all required skills exist and are validated.

Step 3 — Select Tools (Minimal Set)

Use only the tools the agent's role requires. Each extra tool broadens the attack surface and dilutes focus:

Red flag: If your list includes execute, web, AND agent simultaneously, ask whether the agent is doing too much — split it.

Common minimal sets:

• Read-only research: [read, search, web]
• File authoring: [read, edit, search]
• Full orchestration: [read, edit, search, execute, web, agent] — only valid for top-level orchestrators

Step 4 — Write .agent.md

Place at: .github/agents/<name>.agent.md

Required frontmatter:

---
name: "Agent Display Name"
description: "Use when..."    # Keyword-rich; critical for subagent discovery
tools: [read, edit, search]   # Minimal set from Step 3
user-invocable: false         # false for subagents, true for picker agents
disable-model-invocation: true
---

Body structure:

1. Identity statement — "You are a specialist at X. Your job is to Y."
2. Skill Routing (if multiple skills) — table mapping task type → skill file path to read
3. Core Workflow — numbered steps for how the agent operates
4. Constraints — explicit DO NOT rules
5. Output Format — exactly what the agent returns

Load ./references/agent-structure.md for the full annotated template with tool aliases, invocation control, and anti-patterns.

After writing .github/agents/<name>.agent.md, regenerate Cursor subagents:

./scripts/generate-cursor-agents.zsh

Step 5 — Validate

AGENT=".github/agents/<name>.agent.md"

# 1. Filename / name-field match
FILENAME=$(basename "$AGENT" .agent.md)
NAME_FIELD=$(grep -m1 '^name:' "$AGENT" | sed 's/name: *"\?//;s/"$//')
if [ -z "$NAME_FIELD" ]; then
  echo "⚠️  name: field absent (optional but recommended)"
elif [ "$FILENAME" = "$NAME_FIELD" ]; then
  echo "✅ filename matches name: $NAME_FIELD"
else
  echo "❌ filename '$FILENAME' != name: '$NAME_FIELD'"
fi

# 2. Required frontmatter fields
for F in description tools user-invocable; do
  grep -q "^$F:" "$AGENT" && echo "✅ $F" || echo "❌ missing: $F"
done

# 3. Description contains trigger words
grep -c "Use when\|Use for\|specialist\|expert" "$AGENT"

# 4. All referenced skill files exist
grep -oE '\.agents/skills/[^/]+/SKILL\.md' "$AGENT" | while read F; do
  [ -f "$F" ] && echo "✅ $F" || echo "❌ missing skill: $F"
done

# 5. Required body sections
for S in "Constraints" "Output Format"; do
  grep -q "^## $S" "$AGENT" && echo "✅ $S" || echo "❌ missing section: $S"
done

# 6. Swiss-army tool guard — warn if all 6 major tools present
TOOL_COUNT=$(grep '^tools:' "$AGENT" | grep -oE '\b(read|edit|search|execute|web|agent)\b' | wc -l | tr -d ' ')
[ "$TOOL_COUNT" -lt 6 ] && echo "✅ tools=$TOOL_COUNT (focused)" || echo "⚠️  tools=$TOOL_COUNT — verify each is essential"

Step 6 — Sync to Active Environment

After creating the .agent.md and all dependency skills, run the repo bootstrap script to refresh symlinks into ~/.copilot/, VS Code's prompts directory, and optional Vibe directories. Without this step, the new agent and skills won't be available to Copilot in the current session.

ROOT="$(git rev-parse --show-toplevel)"
"$ROOT/scripts/setup-copilot-globals.sh" --dry-run
"$ROOT/scripts/setup-copilot-globals.sh" --force

Flags:

• --dry-run — preview what will be linked without making changes (use first to verify)
• --force — replace existing symlinks if they already exist

The bootstrap script creates symlinks from:

• ~/.copilot/agents/ → agent source files
• ~/.copilot/skills/ → skill source files
• ~/Library/Application Support/Code/User/prompts/agents/ → VS Code prompts directory
• ~/.claude/skills/ → Claude Code skill files in .claude/skills/ (if present)

Always run the bootstrap script after creating or modifying any agent or skill file.

Claude Code note: The tools: values in .agent.md (read, edit, search, execute, web, agent) are Copilot aliases. The Claude Code equivalents are Read, Edit/Write, Bash, WebSearch/WebFetch, Agent. If creating a companion .claude/skills/<name>.md file for Claude Code slash-command access, run the bootstrap script to link it to ~/.claude/skills/.

Step 7 — Troubleshoot Common Issues

Agent skill not loading — "failed to load" error

• Check that the .agent.md filename exactly matches the name: field in frontmatter (kebab-case, no extension).
• Ensure --- delimiters are present at lines 1 and N, with no leading spaces.

Agent triggers for unrelated queries

• Tighten the description field. Add an explicit Do NOT use for: clause with specific exclusions.
• Check that user-invocable: false is set for subagents not meant to be directly invoked.

Agent ignores skill routing instructions

• The skill referenced in the routing table must be enabled. Verify with /skills in the CLI.
• Use the exact skill name as it appears in the skill's name: frontmatter field.

Agent runs sub-agent but never returns a result

• Sub-agent handoff requires the parent agent to await and surface results. Add an explicit step: "Return the sub-agent output to the user."

Tool calls blocked

• The tool is not in the agent's tools: list. Add it. Prefer the minimal set — only add what the agent actively uses.

Completion Checks

• Agent name is kebab-case and matches the filename (without .agent.md)
• description contains ≥3 trigger keywords for subagent discovery
• tools list is minimal — no tools included "just in case"
• user-invocable is set explicitly
• All referenced skills exist in .agents/skills/
• .cursor/agents/<name>.md exists and is current (./scripts/generate-cursor-agents.zsh --check)
• Body has: identity statement, constraints (DO NOT rules), output format
• Identity statement names a specific, bounded role (not "helpful assistant", "assistant", or "agent")
• At least one adjacent task is explicitly excluded in the Constraints section (scope boundary is documented)
• setup-copilot-globals.sh was run and new agent/skills are symlinked in ~/.copilot/

References

• Agent Structure Template