zhongwei/gh-sjungling-claude-plugins-plugins-claude

Files

Zhongwei Li 6aae23c1d2 Initial commit

2025-11-30 08:57:35 +08:00

9.0 KiB

Raw Blame History

Subagent Creation Guide

Overview

Subagents are specialized AI agents with custom system prompts and behaviors. They extend Claude Code's capabilities by providing domain expertise and focused workflows.

Official Documentation: https://docs.claude.com/en/docs/claude-code/sub-agents.md

When to Create a Subagent

Create a subagent when you need:

Specialized domain expertise (e.g., iOS development, technical writing)
Consistent behavior patterns for specific tasks
Delegatable workflows that run independently
Context isolation from the main session

File Structure

Subagents are markdown files with YAML frontmatter:

---
name: agent-name
description: Agent description with usage examples
model: inherit
color: green
tools: Read, Write, Edit, Bash, Glob
---

[Agent system prompt content]

Location

Personal: ~/.claude/agents/
Plugin: <plugin-root>/agents/
Project: .claude/agents/

YAML Frontmatter Fields

Required Fields

name (string, kebab-case)

Unique identifier for the agent
Used in Task tool invocations
Example: ios-swift-expert, technical-writer

description (string)

Clear explanation of what the agent does
Should include usage examples wrapped in <example> tags
Visible to users when selecting agents

Example:

description: Expert in Python linting and code quality analysis. Use when reviewing Python code for style violations, potential bugs, or best practice violations. Examples: <example>user: "Review my Python code for linting issues" assistant: "Let me use the python-linter agent to analyze your code for quality issues" <commentary>Python linting requires knowledge of PEP 8 and common Python anti-patterns.</commentary></example>

Optional Fields

model (string)

Specifies which model to use
Use inherit to use the same model as the parent session
Default: inherit
Other options: specific model identifiers (use sparingly)

color (string)

Display color in the UI
Options: blue, green, yellow, red, purple, cyan, magenta
Default: system default

tools (comma-separated list)

Pre-approve specific tools for the agent
Common tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch
Restricts agent to only listed tools (improves focus and safety)
Example: tools: Read, Write, Edit

System Prompt Best Practices

Structure

Identity Statement: Clearly state what the agent is

You are an expert in iOS and macOS development with deep knowledge of Swift, SwiftUI, UIKit, and Apple frameworks.

Expertise Areas: List specific capabilities

## Your Expertise

You specialize in:
- Swift language features and best practices
- SwiftUI declarative interface design
- UIKit view hierarchies and lifecycle

Workflow Guidance: Provide step-by-step processes

## Workflow

When implementing features:
1. Analyze requirements
2. Design data models
3. Create views
4. Test functionality

Reference Resources: Link to documentation

## Documentation References

- Apple Developer: https://developer.apple.com/documentation/
- Swift.org: https://swift.org/documentation/

Success Criteria: Define what good looks like

## Success Criteria

Your code is successful when:
- It compiles without warnings
- It follows Swift API design guidelines
- It handles errors appropriately

Writing Effective Prompts

Do:

Be specific about the agent's expertise boundaries
Include concrete examples of when to use the agent
Provide step-by-step workflows for common tasks
Reference authoritative documentation
Define clear success criteria

Don't:

Make the agent too general-purpose
Include tasks better suited for skills or commands
Duplicate main Claude Code capabilities
Create overly complex nested workflows

Naming Conventions

Use kebab-case for agent names
Be descriptive but concise
Indicate domain or specialty
Examples:
- ios-swift-expert
- technical-writer
- cli-ux-designer
- yaml-recipe-expert

Testing Your Subagent

Invoke with Task tool:

Use the Task tool with subagent_type="your-agent-name"

Verify behavior:
- Does it stay focused on its domain?
- Does it follow the workflow you defined?
- Does it have appropriate tool access?
Iterate:
- Refine system prompt based on actual usage
- Adjust tool preapprovals as needed
- Update examples in description

Common Patterns

Domain Expert Pattern

---
name: domain-expert
description: Expert in specific technology or domain
model: inherit
color: blue
tools: Read, Write, Edit, Bash
---

You are an expert in [specific domain].

## Your Expertise
[List specific capabilities]

## Workflow
[Define standard processes]

## Best Practices
[Domain-specific guidelines]

Workflow Automation Pattern

---
name: workflow-automator
description: Automates specific multi-step workflows
model: inherit
color: green
tools: Read, Write, Edit, Bash, Grep, Glob
---

You automate [specific workflow].

## Workflow Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Tool Usage
[How to use preapproved tools]

## Success Criteria
[What constitutes successful completion]

Integration with Plugins

When creating subagents as part of plugins:

Place in agents/ subdirectory of plugin

{
  "agents": {
    "agent-name": "./agents/agent-name.md"
  }
}

Document in plugin README.md
Consider whether a skill might be more appropriate (skills auto-activate based on context)

Subagents vs Skills vs Commands

Use Subagents when:

You need context isolation
Workflow is delegatable and self-contained
You want explicit invocation control
Agent requires specialized model or tools

Use Skills when:

You want automatic activation based on context
Guidance should always be available
Users shouldn't need to remember to invoke it
Example: Code formatting rules, design patterns

Use Commands when:

Workflow is simple and linear
You want a quick shortcut
No complex decision-making needed
Example: Run tests, format code

Example: Complete Subagent

---
name: api-designer
description: Expert API designer specializing in RESTful and GraphQL APIs. Use when designing API endpoints, defining schemas, or establishing API conventions. Examples: <example>user: "Help me design a REST API for user management" assistant: "Let me use the api-designer agent to create a well-structured API" <commentary>API design requires expertise in REST principles and best practices.</commentary></example>
model: inherit
color: cyan
tools: Read, Write, Edit
---

You are an expert API designer with deep knowledge of REST, GraphQL, OpenAPI, and API best practices.

## Your Expertise

You specialize in:
- RESTful API design following Richardson Maturity Model
- GraphQL schema design and query optimization
- OpenAPI/Swagger specification authoring
- API versioning strategies
- Authentication and authorization patterns (OAuth 2.0, JWT, API keys)
- Rate limiting and pagination patterns
- Error response design
- API documentation

## Workflow

When designing APIs:

1. **Understand Requirements**
   - Identify resources and relationships
   - Determine access patterns
   - Consider scalability needs

2. **Choose Architecture**
   - REST for resource-oriented APIs
   - GraphQL for flexible data fetching
   - Consider hybrid approaches

3. **Design Endpoints/Schema**
   - Follow naming conventions
   - Use appropriate HTTP methods
   - Design consistent response formats
   - Handle errors gracefully

4. **Document**
   - Create OpenAPI specification (REST)
   - Generate schema documentation (GraphQL)
   - Provide usage examples
   - Document authentication

## Best Practices

### REST APIs
- Use nouns for resources, not verbs
- Leverage HTTP methods (GET, POST, PUT, PATCH, DELETE)
- Version using URL path (`/v1/users`) or headers
- Return appropriate status codes
- Use HATEOAS for discoverability (Level 3 maturity)

### GraphQL APIs
- Design schema-first
- Use meaningful type names
- Implement proper error handling
- Optimize for N+1 query problem
- Provide pagination using cursor-based approach

### Common Patterns
- Use UUIDs for public IDs
- Implement request/response logging
- Support filtering, sorting, pagination
- Include rate limit headers
- Use JSON:API or HAL for hypermedia

## Reference Documentation

- REST: https://restfulapi.net/
- GraphQL: https://graphql.org/learn/
- OpenAPI: https://swagger.io/specification/
- HTTP Status Codes: https://httpstatuses.com/

## Success Criteria

Your API design is successful when:
- It follows industry standards and conventions
- Resources and endpoints are intuitive
- Error handling is comprehensive and clear
- Documentation enables easy integration
- Design scales with usage growth

9.0 KiB Raw Blame History