agentleFS
DGouronDGouron/review-flow/.claude/skills/agent-creator/SKILL.md

agent-creator

Skill44 starsChanged 6 months agoMITView on GitHub

Guide for creating optimized Claude Code agents. Use to design a new specialized agent, a swarm sub-agent, or a multi-agent workflow. Follows the Skill → Agent (preloaded skills) → Skill orchestration pattern.

29 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use security-review and code-review.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SentrySkill

    security-review

    Finds exploitable application security vulnerabilities in code changes. Use for Warden security scans, appsec review, OWASP-style checks, authentication or authorization bugs, injection, XSS, SSRF, path traversal, secrets, unsafe crypto, webhook verification, open redirects, or sensitive data exposure.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 5 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 27 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before creating the agent, clarify:

    line 54
  2. Very specific:

    Create .claude/agents/<agent-name>.md with this structure:

    line 65
  3. Distinctive:

    If the agent creates or modifies code, add a self-review phase:

    line 121
  4. Very specific:

    Before publishing the agent, run references/checklist.md.

    line 143
  5. Distinctive:

    Prefer targeted agents (5-10 files) over omniscient ones

    line 171
  6. Distinctive:

    If > 10 files to read → split into parallel sub-agents

    line 172

“Common” is measured: kept by at least 6 in 10 of the 27 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Agent Creator

Activation

This skill activates for:

  • Creating a new specialized agent (sub-agent, swarm agent)
  • Designing a multi-agent workflow
  • Optimizing an existing agent
  • Creating a feature-specific or domain-specific agent

Core Principle

A feature-specific agent with a targeted persona always outperforms a generic agent.

❌ "You are a senior backend engineer"
✅ "You are a TDD implementation agent for the ReviewFlow Clean Architecture Fastify/TypeScript project"

Orchestration Architecture

Skill (user entry point, triggers)
  → Agent .claude/agents/*.md (targeted persona, preloaded skills)
    → Skill (knowledge injected into agent context)
LevelRoleLocation
SkillEntry point, orchestration.claude/skills/<name>/SKILL.md
AgentAutonomous execution, dedicated context.claude/agents/<name>.md
Skill (preloaded)Knowledge injected at startupskills: in agent YAML

Agent vs Inline Prompt

CriteriaAgent .claude/agents/Inline prompt
Skills preloadedskills: [tdd, architecture]Must read manually
ReusableFrom any skillLocked in one skill
Configurationmodel, maxTurns, permissions, tools, hooksLimited to Agent tool
DiscoverabilityVisible in .claude/agents/Hidden

Rule: ALWAYS create .claude/agents/<name>.md. Never inline prompts in references/.

Creation Workflow

Phase 1: INTAKE — Define the need

Before creating the agent, clarify:

  1. What problem does it solve? — One sentence, not a paragraph
  2. What is its scope? — Files, modules, or full codebase
  3. How often will it be used? — One-off or recurring
  4. Does a skill/agent already cover this? — Check .claude/skills/ AND .claude/agents/
  5. What is its expected output? — Files created, report, refactoring
  6. Which existing skills should it know? — For preloading

Phase 2: DESIGN — Create the agent file

Create .claude/agents/<agent-name>.md with this structure:

---
name: <agent-name>
description: "Use this agent to [specific action]. [Additional context]."
tools: Read, Glob, Grep, LS                    # Explicit allowlist
model: sonnet|opus                              # sonnet for read-only, opus for code
maxTurns: 15                                    # Adjust to scope
permissionMode: default|bypassPermissions       # bypassPermissions if writing
skills:                                         # Preloaded into context
  - <skill-name-1>
  - <skill-name-2>
---

# <Agent Name>

## Persona (2-3 lines)

You are a [specific role] for [precise context].

## Coding Standards

Read `.claude/rules/coding-standards.md` BEFORE working.

## Mission (numbered, max 7 steps)

1. [Step]
2. [Step]
3. ...

## Constraints (max 10 rules)

- [Rule]
- [Rule]

## Output format

[Exact template of deliverable]

YAML Frontmatter — Supported fields

FieldRequiredDescription
nameYesUnique identifier, lowercase + hyphens
descriptionYesWhen to delegate to this agent — Claude matches on this field
toolsRecommendedTool allowlist. Omitted = all tools
modelNosonnet (fast), opus (quality), haiku (light). Default: inherit
maxTurnsNoAgentic turn limit. Default: no limit
permissionModeNodefault, acceptEdits, dontAsk, bypassPermissions, plan
skillsNoList of preloaded skills. Content injected at startup
hooksNoLifecycle hooks: PreToolUse, PostToolUse, Stop

Phase 3: SELF-REVIEW — Decide if the agent self-reviews

If the agent creates or modifies code, add a self-review phase:

## Phase N: SELF-REVIEW (autonomous loop)

After completing the mission:

### Step 1: Run tests
yarn test:ci

### Step 2: Reread each created file
Check: naming, imports, TypeScript, architecture, tests

### Step 3: Fix loop (max 3 iterations)
For each violation: fix → rerun tests → confirm

### Step 4: Escalate
If blocked after 3 iterations → list issues in report

Phase 4: VALIDATION — Checklist

Before publishing the agent, run references/checklist.md.

Phase 5: ITERATION

After first use:

  • Did the output match expectations?
  • Was the context sufficient?
  • Were preloaded skills the right ones?
  • Did the agent drift? Why?
  • Did self-review catch real problems?
  • Adjust the agent file and re-test

Sizing Rules

Agent file

ElementMax sizeWhy
Persona3 linesBeyond this, dilutes focus
Project context10 linesAgent has preloaded skills + must read code
Mission5-7 stepsBeyond this, split into sub-agents
Constraints10 rulesBeyond this, create a dedicated skill
Skills preloaded3 maxBeyond this, context too heavy at startup

Context window

  • Preloaded skills consume context (~3-5k tokens per skill)
  • An agent reading 20+ files risks degradation
  • Prefer targeted agents (5-10 files) over omniscient ones
  • If > 10 files to read → split into parallel sub-agents

When to split into sub-agents

SignalAction
Mission > 7 stepsSplit into 2-3 sequential agents
Files to read > 10Split by category (parallel swarm)
Output > 500 linesOne agent synthesizes, another details
Scope cross-moduleOne agent per module
Skills preloaded > 3Split — too much knowledge dilutes focus

ReviewFlow Project Specifics

Agents created for this project must respect:

  • Clean Architecture: dependency rule, 5 layers (entities, usecases, interface-adapters, frameworks, shared)
  • TDD Detroit School: failing test first, mocks only for I/O via stubs
  • Conventions: full words, camelCase .ts, aliases @/ + .js extension
  • Language: code/tests in English, user-facing text in French
  • Patterns: Gateway contracts in entities/, impl in interface-adapters/gateways/
  • Testing: Factories (static create()), stub gateways, yarn test:ci
  • Coding standards: point to .claude/rules/coding-standards.md

Agent Patterns

See references/agent-patterns.md for reusable templates.

Anti-patterns

See references/anti-patterns.md for common mistakes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.