agentleFS
Badhon-00Badhon-00/MDCP/skills/agent-development/SKILL.md

agent-development

Skill2 starsChanged 5 days agoMITView on GitHub

This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.

15 other projects use a version of this, 10 of them edited; 6 of 10 edited versions we compared changed its rules.

How people change it

6 of 10 edited versions changed its rules.

Of the 10 edited versions we compared: 1 keep every rule, 3 are an older text, 6 made changes of their own.

Not in older versions

  1. Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptionsmissing from 3 of 3

Rules people drop

  1. Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptionsdropped by 6 of 6

We split this file and each edited version into the rules they give an agent and match them by wording. A version that adds no rule of its own and has not changed since this file last did reads as an older text, so what it lacks is not counted as dropped. We keep no past texts of a file, so that is inferred, and an edited version that started from an older text still counts its gaps as drops.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. 24 are common, 1 is distinctive, and 2 are very specific to this project.

  • 24

    Common

    Most of the 12 edited versions we read keep these.

  • 1

    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. Common:

    Pattern: Must start and end with alphanumeric

    line 60
  2. Distinctive:

    Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions

    line 93
  3. Very specific:

    Recommendation: Use inherit unless agent needs specific model capabilities.

    line 105
  4. Common:

    Use consistent colors for similar agent types

    line 115
  5. Common:

    Default: If omitted, agent has access to all tools

    line 132
  6. Common:

    Write in second person ("You are...", "You will...")

    line 181
  7. Common:

    Write in first person ("I am...", "I will...")

    line 190
  8. Common:

    Leave output format undefined

    line 193
  9. Common:

    Use this prompt pattern (extracted from Claude Code):

    line 201
  10. Common:

    Write description with examples

    line 233
  11. Common:

    Write system prompt with structure above

    line 237
  12. Common:

    Must start and end with alphanumeric

    line 252
  13. Common:

    No underscores, spaces, or special characters

    line 253
  14. Common:

    Create test scenarios to verify agent triggers correctly:

    line 291
  15. Common:

    Write agent with specific triggering examples

    line 293
  16. Common:

    Use similar phrasing to examples in test

    line 294
  17. Common:

    Check Claude loads the agent

    line 295
  18. Common:

    Verify agent provides expected functionality

    line 296
  19. Common:

    Ensure system prompt is complete:

    line 300
  20. Common:

    Check it follows process steps

    line 303
  21. Common:

    Verify output format is correct

    line 304
  22. Common:

    Test edge cases mentioned in prompt

    line 305
  23. Very specific:

    test-agent-trigger.sh: - Test if agent triggers correctly

    line 385
  24. Common:

    Write frontmatter with all required fields

    line 394
  25. Common:

    Write system prompt following best practices

    line 395
  26. Common:

    Test triggering with real scenarios

    line 398
  27. Common:

    Document agent in plugin README

    line 399

“Common” is measured: kept by at least 6 in 10 of the 12 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 Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.

Key concepts:

  • Agents are FOR autonomous work, commands are FOR user-initiated actions
  • Markdown file format with YAML frontmatter
  • Triggering via description field with examples
  • System prompt defines agent behavior
  • Model and color customization

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

## When to invoke

[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples:

  • code-reviewer
  • test-generator
  • api-docs-writer
  • security-analyzer

Bad examples:

  • helper (too generic)
  • -agent- (starts/ends with hyphen)
  • my_agent (underscores not allowed)
  • ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.

Must include:

  1. Triggering conditions ("Use this agent when...")
  2. A short prose summary of the typical trigger scenarios
  3. A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios

Format:

Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.

Best practices:

  • Name 2-4 trigger scenarios in the prose summary
  • Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
  • Cover different phrasings of the same intent
  • Be specific about when NOT to use the agent
  • Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions

model (required)

Which model the agent should use.

Options:

  • inherit - Use same model as parent (recommended)
  • sonnet - Claude Sonnet (balanced)
  • opus - Claude Opus (most capable, expensive)
  • haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines:

  • Choose distinct colors for different agents in same plugin
  • Use consistent colors for similar agent types
  • Blue/cyan: Analysis, review
  • Green: Success-oriented tasks
  • Yellow: Caution, validation
  • Red: Critical, security
  • Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

  • Read-only analysis: ["Read", "Grep", "Glob"]
  • Code generation: ["Read", "Write", "Grep"]
  • Testing: ["Read", "Bash", "Grep"]
  • Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

  • Write in second person ("You are...", "You will...")
  • Be specific about responsibilities
  • Provide step-by-step process
  • Define output format
  • Include quality standards
  • Address edge cases
  • Keep under 10,000 characters

❌ DON'T:

  • Write in first person ("I am...", "I will...")
  • Be vague or generic
  • Omit process steps
  • Leave output format undefined
  • Skip quality guidance
  • Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

  1. Choose agent identifier (3-50 chars, lowercase, hyphens)
  2. Write description with examples
  3. Select model (usually inherit)
  4. Choose color for visual identification
  5. Define tools (if restricting access)
  6. Write system prompt with structure above
  7. Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

  • 3-50 characters
  • Lowercase letters, numbers, hyphens only
  • Must start and end with alphanumeric
  • No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

  • Single plugin: agent-name
  • With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

  1. Write agent with specific triggering examples
  2. Use similar phrasing to examples in test
  3. Check Claude loads the agent
  4. Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

  1. Give agent typical task
  2. Check it follows process steps
  3. Verify output format is correct
  4. Test edge cases mentioned in prompt
  5. Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
color: blue
---

You are an agent that [does X].

## When to invoke

- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

FieldRequiredFormatExample
nameYeslowercase-hyphenscode-reviewer
descriptionYesProse triggersUse when... Typical triggers include...
modelYesinherit/sonnet/opus/haikuinherit
colorYesColor nameblue
toolsNoArray of tool names["Read", "Grep"]

Best Practices

DO:

  • ✅ Name 2-4 trigger scenarios in the description (as prose)
  • ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
  • ✅ Write specific triggering conditions
  • ✅ Use inherit for model unless specific need
  • ✅ Choose appropriate tools (least privilege)
  • ✅ Write clear, structured system prompts
  • ✅ Test agent triggering thoroughly

DON'T:

  • ❌ Use generic descriptions without trigger scenarios
  • ❌ Omit triggering conditions
  • ❌ Give all agents same color
  • ❌ Grant unnecessary tool access
  • ❌ Write vague system prompts
  • ❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

  • references/system-prompt-design.md - Complete system prompt patterns
  • references/triggering-examples.md - Example formats and best practices
  • references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

  • agent-creation-prompt.md - AI-assisted agent generation template
  • complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

  • validate-agent.sh - Validate agent file structure
  • test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

  1. Define agent purpose and triggering conditions
  2. Choose creation method (AI-assisted or manual)
  3. Create agents/agent-name.md file
  4. Write frontmatter with all required fields
  5. Write system prompt following best practices
  6. Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
  7. Validate with scripts/validate-agent.sh
  8. Test triggering with real scenarios
  9. Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

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.