Branch skill for building and improving agents. Use when creating new agents, adapting marketplace agents, validating agent structure, writing system prompts, or improving existing agents. Triggers: 'create agent', 'improve agent', 'validate agent', 'fix agent', 'agent frontmatter', 'system prompt', 'adapt agent', 'customize agent', 'agent examples', 'agent tools'.
Builds and improves autonomous agents with proper frontmatter, examples, and system prompts. Triggers on phrases like "create agent", "improve agent", "validate agent", or "fix agent".
/plugin marketplace add henmessi/plugin-dev/plugin install henmessi-plugin-dev@henmessi/plugin-devThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Build and improve agents following the agents-management policy.
Primary policy: JARVIS-03 → .claude/skills/agents-management/SKILL.md
This branch executes the policy defined by JARVIS-03. Always sync with Primary before major operations.
Task Received
│
├── Create new agent? ───────────────> Workflow 1: Build
│ └── What complexity?
│ ├── Simple (responder) ──────> Pattern 3: Small (2-4k words)
│ ├── Developer ───────────────> Pattern 2: Medium (3-8k words)
│ └── Architect ───────────────> Pattern 1: Large (10k+ words)
│
├── Adapt marketplace agent? ────────> Workflow 3: Adapt
│
├── Fix existing agent? ─────────────> Workflow 2: Improve
│
└── Validate agent? ─────────────────> Validation Checklist
Agents are autonomous subprocesses that handle complex, multi-step tasks independently.
Key concepts:
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:
<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>
<example>
[Additional example...]
</example>
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
You are [agent role description]...
**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]
**Analysis Process:**
[Step-by-step workflow]
**Output Format:**
[What to return]
Agent identifier used for namespacing and invocation.
Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric
Validation:
✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
Rules:
Good examples:
code-reviewertest-generatorapi-docs-writersecurity-analyzerBad examples:
helper (too generic)-agent- (starts/ends with hyphen)my_agent (underscores not allowed)ag (too short, < 3 chars)Defines when Claude should trigger this agent. This is the most critical field.
Must include:
<example> blocks showing usage<commentary> explaining why agent triggersLength: 10-5,000 characters Best: 200-1,000 characters with 2-4 examples
Format:
Use this agent when [conditions]. Examples:
<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>
[More examples...]
Best practices:
Which model the agent should use.
| Option | Description | Use For |
|---|---|---|
inherit | Same as parent (recommended) | Default choice |
sonnet | Claude Sonnet (balanced) | Developers, debuggers |
opus | Claude Opus (most capable) | Architects, complex decisions |
haiku | Claude Haiku (fast, cheap) | Simple validators, quick tasks |
Visual identifier for agent in UI.
| Color | Use For |
|---|---|
| blue/cyan | Analysis, review, architecture |
| green | Generation, creation, success |
| yellow | Validation, caution, warnings |
| red | Security, critical, destructive |
| magenta | Creative, transformation |
Restrict agent to specific tools.
Format: Array of tool names
tools: ["Read", "Write", "Grep", "Bash"]
Default: If omitted, agent has access to all tools
Common tool sets:
| Use Case | Tools |
|---|---|
| Read-only analysis | ["Read", "Grep", "Glob"] |
| Code generation | ["Read", "Write", "Grep"] |
| Testing | ["Read", "Bash", "Grep"] |
| Full access | Omit field or use ["*"] |
Best practice: Limit tools to minimum needed (principle of least privilege)
Answer these questions:
| Pattern | Word Count | Model | Use For |
|---|---|---|---|
| Architect | 10,000-15,000 | opus | Backend, cloud, database, K8s architects |
| Developer | 3,000-8,000 | sonnet/inherit | Frontend, mobile, feature developers |
| Responder | 2,000-4,000 | sonnet/haiku | Incident response, debugging, quick tasks |
---
name: agent-name
description: Use this agent when [specific conditions]. [Expertise description]. Masters [technologies]. Use PROACTIVELY when [trigger scenarios]. Examples:
<example>
Context: [Situation that triggers agent]
user: "[User's request]"
assistant: "I'll use the [agent-name] agent to [action]."
<commentary>
[Why this agent is appropriate]
</commentary>
</example>
<example>
Context: [Another scenario]
user: "[Request]"
assistant: "[Response using agent]"
<commentary>
[Reasoning]
</commentary>
</example>
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
Pattern 1: Architect (Large - 10k+ words)
You are [Domain] Architect specializing in [specific areas].
**Expert Purpose:**
[Comprehensive description of expertise - 2-3 paragraphs]
**Core Capabilities:**
### [Area 1]
- **[Sub-topic]**: [Details with sub-items]
- **[Sub-topic]**: [Details]
### [Area 2]
[Continue with 8-12 capability areas]
**Behavioral Traits:**
- [6-10 personality/approach traits]
- Proactively identifies architectural risks
- Balances ideal solutions with pragmatic constraints
- Documents decisions and rationale
**Knowledge Base:**
- [Technology 1]: [Expertise level and specifics]
- [Technology 2]: [Expertise level]
**Response Approach:**
1. Understand the full context and constraints
2. Identify architectural implications
3. Consider multiple approaches
4. Evaluate trade-offs
5. Recommend with clear rationale
6. Provide implementation guidance
7. Document decisions
8. Consider future maintainability
**Example Interactions:**
- "Design an API for..." → Analyze requirements, propose structure, document decisions
- "How should we scale..." → Evaluate options, recommend approach, plan implementation
**Workflow Position:**
- **After**: Requirements gathering, initial planning
- **Complements**: Backend developers, DevOps engineers
- **Enables**: Implementation teams, code reviewers
**Output Format:**
Provide architectural recommendations as:
- Executive summary (2-3 sentences)
- Detailed analysis (structured sections)
- Decision rationale (why this approach)
- Implementation guidance (next steps)
- Risk considerations (what could go wrong)
Pattern 2: Developer (Medium - 3-8k words)
You are [Domain] Developer specializing in [frameworks/technologies].
**Expert Purpose:**
[Clear focus statement - 1 paragraph]
**Core Capabilities:**
1. [Primary capability with details]
2. [Secondary capability]
3. [Additional capabilities - 5-8 total]
**Modern Stack Focus:**
- [Framework 1]: [Version/approach]
- [Framework 2]: [Details]
**Best Practices:**
- [Practice 1]
- [Practice 2]
**Response Approach:**
1. Understand requirements and constraints
2. Check existing patterns in codebase
3. Implement following established standards
4. Verify functionality works correctly
**Example Interactions:**
- "Build a component..." → Check existing patterns, implement, test
- "Fix this issue..." → Diagnose, implement fix, verify
**Output Format:**
- Working code with inline comments
- Explanation of key decisions
- Usage examples if applicable
Pattern 3: Responder (Small - 2-4k words)
You are [Domain] Responder specializing in [area].
**Expert Purpose:**
Rapid [problem type] resolution with [approach].
**Immediate Actions:**
1. [First 5 minutes actions]
2. [Triage steps]
**Severity Matrix:**
| Level | Impact | Response Time | Actions |
|-------|--------|---------------|---------|
| P0 | Critical | Immediate | [Actions] |
| P1 | High | 15 min | [Actions] |
| P2 | Medium | 1 hour | [Actions] |
**Diagnostic Process:**
1. [Step 1]
2. [Step 2]
3. [Step 3]
**Common Pitfalls:**
- [Mistake 1]: [How to avoid]
- [Mistake 2]: [Correct approach]
**Output Format:**
- Status: [Current state]
- Diagnosis: [What's wrong]
- Action: [What to do]
- Timeline: [Expected resolution]
Save to: agents/[name].md
Run validation checklist.
# Read agent file
cat agents/[name].md
# Check for issues:
# - Missing examples in description?
# - System prompt too short/long?
# - Wrong model for complexity?
# - Missing tools restriction?
| Component | Check | Common Issues |
|---|---|---|
| name | lowercase-hyphens? | Spaces, uppercase, too short |
| description | Has examples? | Missing <example> blocks |
| description | PROACTIVELY triggers? | Only reactive triggers |
| model | Matches complexity? | opus for simple, haiku for complex |
| color | Semantic meaning? | Random color choice |
| system prompt | Has sections? | Missing capabilities/output format |
| system prompt | Right length? | Architect <500 words = too short |
Adding examples to description:
description: ... Examples:
<example>
Context: [Scenario]
user: "[Request]"
assistant: "I'll use [agent] to [action]."
<commentary>
[Why appropriate]
</commentary>
</example>
Adding Workflow Position:
**Workflow Position:**
- **After**: [What happens before this agent]
- **Complements**: [Related agents]
- **Enables**: [What this agent enables]
Expanding Core Capabilities:
Add 8-12 capability areas for architects, 5-8 for developers.
Adding JARVIS Integration:
**JARVIS Integration:**
- Reference category's Primary Skill for domain knowledge
- Use category's MCP tools when available
- Follow category's established patterns
Run full validation checklist.
When taking an agent from wshobson-agents, obra-superpowers, or similar:
cat marketplace-plugin/agents/[agent].md
Note:
| Original Focus | JARVIS Target |
|---|---|
| Orchestration | Plugin-Orchestrator |
| Self-improvement | plugin-dev |
| Data/analytics | Plugin-BigQuery-[Cat] |
| Domain-specific | Plugin-Category-[Cat] |
Original (generic):
description: Expert backend architect for designing scalable APIs...
Adapted (JARVIS-specific):
description: Expert backend architect for JARVIS ecosystem. Use when designing APIs for MCP servers, planning microservices architecture, or establishing backend patterns for categories. Use PROACTIVELY when starting backend development. Examples:
<example>
Context: Creating MCP server for new category
user: "Design the API for the Asana MCP server"
assistant: "I'll use the backend-architect agent to design the API structure."
<commentary>
MCP server creation requires careful API design - this agent specializes in this.
</commentary>
</example>
**Workflow Position:**
- **After**: Category creation, requirements gathering
- **Complements**: frontend-developer, database-architect
- **Enables**: MCP implementation, testing
Add category-specific references:
**JARVIS Integration:**
- Reference category's Primary Skill for domain knowledge
- Use category's MCP tools when available
- Follow category's established patterns
- Check BigQuery for relevant data
Run full validation checklist.
plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md
All .md files in agents/ are auto-discovered.
Agents are namespaced automatically:
agent-nameplugin:subdir:agent-nameWhen multiple plugins have agents:
Create test scenarios to verify agent triggers correctly:
Ensure system prompt is complete:
# Validate agent structure
# Check frontmatter fields
cat agents/my-agent.md | head -20
# Check for required sections in system prompt
grep -E "Core Capabilities|Response Approach|Output Format" agents/my-agent.md
For quick agent creation:
---
name: simple-agent
description: Use this agent when [condition]. Examples:
<example>
Context: [Scenario]
user: "[Request]"
assistant: "Using simple-agent to [action]."
<commentary>
[Why this agent fits]
</commentary>
</example>
model: inherit
color: blue
---
You are an agent that [does X].
**Process:**
1. [Step 1]
2. [Step 2]
3. [Step 3]
**Output:** [What to provide]
agents/ directory with .md extensionname: lowercase, hyphens only, 3-50 charactersname: starts and ends with alphanumericdescription: starts with "Use this agent when..."description: includes "Use PROACTIVELY when..."description: has 2-4 <example> blocksdescription: each example has Context, user, assistant, commentarymodel: appropriate for complexity (inherit/sonnet/opus/haiku)color: matches agent purpose semanticallytools: restricted appropriately (if needed)| Agent Type | Recommended Model | Reason |
|---|---|---|
| Architects (backend, cloud, database) | opus | Complex decisions, long prompts |
| Developers (frontend, mobile) | sonnet or inherit | Balanced speed/quality |
| Debuggers, responders | sonnet | Speed matters |
| Validators, simple checks | haiku | Fast, focused |
| Unknown/general | inherit | Use parent's model |
| Issue | Diagnosis | Fix |
|---|---|---|
| Agent never triggers | Description too vague | Add specific trigger conditions and examples |
| Agent triggers incorrectly | Examples too broad | Make examples more specific |
| Wrong complexity | haiku running architect tasks | Change model to opus |
| No examples | description lacks <example> | Add 2-4 real scenarios |
| Vague output | No Output Format section | Add explicit format spec |
| Generic prompt | Missing JARVIS context | Add Workflow Position, integration notes |
| Too short for architect | <500 words system prompt | Expand capabilities, add sections |
| Tools too broad | No restrictions | Add appropriate tool limits |
DO:
inherit for model unless specific needDON'T:
Before executing any workflow:
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.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.