agentleFS
Sign inStart free
ralphkraussralphkrauss/agent-orchestrator/.agents/skills/create-agent/SKILL.md

create-agent

Skill4 starsChanged 6 months agoMITView on GitHub

Create effective project-level agent definitions in `.agents/agents/` with clear responsibilities, practical constraints, and concise prompts. Use when the user asks to create, refine, or standardize custom agents.

We split this skill into the rules it gives an agent

18 rules. 0 are common, 17 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 35 edited versions we read keep these.

  • 17

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create agents that are easy for Claude to delegate to.

    line 12
  2. Distinctive:

    Keep definitions concise and specific.

    line 13
  3. Distinctive:

    Ensure project scope so agents are shareable in git.

    line 15
  4. Distinctive:

    Use YAML frontmatter plus a short markdown prompt body.

    line 20
  5. Distinctive:

    Keep names lowercase with hyphens.

    line 21
  6. Distinctive:

    Keep the whole file concise (prefer practical rules over long prose).

    line 22
  7. Very specific:

    Start with model: inherit unless there is a clear reason to change it.

    line 40
  8. Distinctive:

    Escalation rules: when to ask the human vs proceed independently.

    line 50
  9. Distinctive:

    Prefer short bullets and action verbs.

    line 56
  10. Distinctive:

    Use specific operational language (e.g., "produce acceptance criteria", "surface risks early").

    line 57
  11. Distinctive:

    Avoid vague instructions like "be helpful" without execution details.

    line 58
  12. Distinctive:

    Avoid duplicate rules across sections.

    line 59
  13. Distinctive:

    Keep terminology consistent across agents.

    line 60
  14. Distinctive:

    When creating agents that own work against third-party vendors, regulators, or upstream APIs:

    line 102
  15. Distinctive:

    Prefer unblock-first behavior across team roles.

    line 107
  16. Distinctive:

    Keep responsibilities distinct (PM orchestrates, analyst clarifies, implementer builds).

    line 108
  17. Distinctive:

    After creating or modifying the agent file, run:

    line 112
  18. Distinctive:

    No overdelivery or noisy-reporting behavior is encouraged.

    line 128

“Common” is measured: kept by at least 6 in 10 of the 35 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

Create Agent

Define agents that are clear, focused, and reusable for this repository.

Goals

  • Create agents that are easy for Claude to delegate to.
  • Keep definitions concise and specific.
  • Encode realistic behavior (deliver outcomes without overpromising).
  • Ensure project scope so agents are shareable in git.

Location and Format

  1. Store each agent in .agents/agents/<agent-name>.md.
  2. Use YAML frontmatter plus a short markdown prompt body.
  3. Keep names lowercase with hyphens.
  4. Keep the whole file concise (prefer practical rules over long prose).

Required Frontmatter

Include at minimum:

---
name: <agent-name>
description: <what it does + when to use it>
tools: <comma-separated tools or omit to inherit>
model: inherit
permissionMode: default
---

Guidance:

  • description should include both WHAT and WHEN (trigger terms).
  • Start with model: inherit unless there is a clear reason to change it.
  • Restrict tools where useful; do not grant broad access by default.

Agent Design Checklist

For each agent, define:

  1. Role boundary: what this agent owns and what it explicitly does not own.
  2. Success definition: what “good output” looks like.
  3. Workflow: short ordered steps the agent follows.
  4. Escalation rules: when to ask the human vs proceed independently.
  5. Communication style: concise, outcome-focused reporting.
  6. Anti-patterns: behaviors to avoid.

Writing Rules

  • Prefer short bullets and action verbs.
  • Use specific operational language (e.g., "produce acceptance criteria", "surface risks early").
  • Avoid vague instructions like "be helpful" without execution details.
  • Avoid duplicate rules across sections.
  • Keep terminology consistent across agents.

Reusable Template

---
name: <agent-name>
description: <specific role>. Use when <trigger scenarios>.
tools: <tools>
model: inherit
permissionMode: default
---

You are a <role> for this repository.

You own:
- <responsibility 1>
- <responsibility 2>

You do not own:
- <non-goal 1>

Workflow:
1. <step 1>
2. <step 2>
3. <step 3>

Escalate only when:
- <high-impact decision>
- <irreversible change>
- <permission-gated action>

Communication:
- <concise update style>

Avoid:
- <anti-pattern 1>
- <anti-pattern 2>

Integration-Heavy Agent Guidance

When creating agents that own work against third-party vendors, regulators, or upstream APIs:

  • Anchor instructions to integration delivery outcomes.
  • Emphasize dependency mapping and third-party constraints.
  • Require early risk surfacing (vendor/API/schema/change windows).
  • Prefer unblock-first behavior across team roles.
  • Keep responsibilities distinct (PM orchestrates, analyst clarifies, implementer builds).

Sync to Claude Code

After creating or modifying the agent file, run:

just ai-sync

This generates the Claude Code mirror in .claude/agents/. Without this step, Claude Code won't discover the new agent.

Always run just ai-sync — do not skip it or leave it for the user.

Validation Before Finalizing

  • File exists in .agents/agents/.
  • Name/description are specific and discoverable.
  • Prompt is concise and actionable.
  • Role boundaries and escalation rules are explicit.
  • No overdelivery or noisy-reporting behavior is encouraged.
  • Ran just ai-sync.

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.

Reviews can't be read right now.

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.

Check your setup, free