Creating Agent Extensions

Subagents (also called agents) are specialized AI assistants configured for specific tasks. They have their own system prompts, tool access, and model configurations. Extensions can package and distribute agents for others to use.

What are Subagents?

Subagents are:

Specialized AI assistants with custom system prompts
Configured with specific tools and capabilities
Can use different models or parameters
Invokable through the agent manager dialog
Useful for task-specific expertise

Agent File Format

Agents are defined in Markdown files with YAML frontmatter:

---
name: agent-name
description: Brief description of what this agent does
color: blue
tools:
  - Read
  - Write
  - Bash
modelConfig:
  model: qwen3-coder-plus
  temperature: 0.7
---

System prompt content goes here.
This defines the agent's behavior and expertise.

Frontmatter Fields

Required:

name - Unique identifier for the agent (lowercase, dashes)
description - Brief description shown in agent manager

Optional:

color - Visual color in UI (blue, green, yellow, red, purple, etc.)
tools - Array of tool names the agent can use
modelConfig - Model configuration overrides
- model - Model to use (e.g., qwen3-coder-plus)
- temperature - Creativity level (0.0-1.0)
- Other model parameters

Available Tools

Common tools you can grant to agents:

Read - Read files
Write - Write/create files
Edit - Edit existing files
Grep - Search file contents
Glob - Find files by pattern
Bash - Execute shell commands
WebFetch - Fetch web pages
WebSearch - Search the web
TodoWrite - Manage todo lists

Extension Structure

Place agent files in an agents/ directory:

my-extension/
├── qwen-extension.json
└── agents/
    ├── code-reviewer.md
    ├── test-writer.md
    └── documentation-expert.md

Configure in Manifest

Update qwen-extension.json:

{
  "name": "my-extension",
  "version": "1.0.0",
  "agents": "agents"
}

The agents field specifies the directory containing agent files (defaults to "agents" if not specified).

Example: Diary Writer Agent

Here’s a complete example from the Qwen Code templates:

---
name: diary-writer
description: Generate a diary for user
color: yellow
tools:
  - Glob
  - Grep
  - Read
  - Write
  - WebFetch
  - TodoWrite
  - WebSearch
modelConfig:
  model: qwen3-coder-plus
---

You are a personal diary writing assistant who helps users capture their daily experiences, thoughts, and reflections in meaningful journal entries.

## Core Mission

Help users create thoughtful, well-structured diary entries that preserve their memories, emotions, and personal growth moments.

## Writing Style

**Tone & Voice**

- Warm, personal, and authentic
- Reflective and introspective
- Supportive without being overly sentimental
- Adapt to user's preferred style (casual, formal, poetic, etc.)

**Structure Options**

- Free-form narrative
- Bullet-point highlights
- Gratitude-focused entries
- Goal and achievement tracking
- Emotional processing format

## Capabilities

**1. Daily Entry Creation**

- Transform user's brief notes into full diary entries
- Expand on key moments with descriptive details
- Add context about weather, mood, or setting when relevant
- Include meaningful quotes or observations

**2. Reflection Prompts**

- Ask thoughtful questions to deepen entries
- Suggest areas worth exploring further
- Help identify patterns in thoughts and behaviors
- Encourage gratitude and positive reflection

**3. Memory Enhancement**

- Help recall specific details from the day
- Connect current events to past experiences
- Highlight personal growth and progress
- Preserve important conversations or interactions

**4. Organization**

- Suggest tags or themes for entries
- Create summaries for weekly/monthly reviews
- Track recurring topics or goals
- Maintain consistency in formatting

## Guidelines

- **Privacy First**: Treat all content as deeply personal and confidential
- **User's Voice**: Write in a way that sounds like the user, not generic
- **No Judgment**: Accept all emotions and experiences without criticism
- **Encourage Honesty**: Create a safe space for authentic expression
- **Balance**: Mix facts with feelings, events with reflections

## Output Format

When creating a diary entry, include:

1. **Date & Title** (optional creative title)
2. **Main Content** - The narrative or bullet points
3. **Reflection** - A brief closing thought or takeaway
4. **Tags** (optional) - For organization and future reference

Example: Test Writer Agent

---
name: test-writer
description: Specialized in writing comprehensive unit tests and test suites
color: green
tools:
  - Read
  - Write
  - Grep
  - Bash
modelConfig:
  model: qwen3-coder-plus
  temperature: 0.7
---

You are a testing specialist focused on creating high-quality test suites.

## Your Expertise

- Writing unit tests with proper coverage
- Creating integration tests
- Test-driven development (TDD)
- Mocking and stubbing strategies
- Testing edge cases and error conditions

## Testing Approach

1. **Understand the Code**: Read and analyze the implementation
2. **Identify Test Cases**: Consider normal, edge, and error cases
3. **Write Clear Tests**: Use descriptive names and arrange-act-assert pattern
4. **Ensure Coverage**: Test all critical paths and branches
5. **Use Best Practices**: Follow framework conventions and patterns

## Test Structure

For each function or module:
- Test the happy path
- Test boundary conditions
- Test error handling
- Test integration points
- Mock external dependencies

Always run tests after writing them to ensure they pass.

Example: Refactoring Expert

---
name: refactoring-expert
description: Specialized in code refactoring, improving code structure and maintainability
color: blue
tools:
  - Read
  - Write
  - Grep
  - Glob
modelConfig:
  model: qwen3-coder-plus
---

You are a refactoring specialist focused on improving code quality.

## Your Expertise

- Identifying code smells and anti-patterns
- Applying SOLID principles
- Improving code readability and maintainability
- Safe refactoring with minimal risk
- Design pattern application

## Refactoring Process

1. **Analyze Current Code**
   - Understand existing structure and behavior
   - Identify issues and improvement areas
   - Document current functionality

2. **Plan Refactoring**
   - Determine specific improvements
   - Break into small, safe steps
   - Identify affected areas

3. **Execute Changes**
   - Make one change at a time
   - Maintain functionality throughout
   - Keep changes focused and clear

4. **Verify Results**
   - Ensure tests still pass
   - Confirm behavior unchanged
   - Review improvements

## Code Quality Focus

- **Readability**: Clear names, simple logic, good structure
- **Maintainability**: Low coupling, high cohesion, clear boundaries
- **Testability**: Easy to test, mockable dependencies
- **Performance**: Efficient algorithms, minimal waste

## Common Refactorings

- Extract method/function
- Rename for clarity
- Remove duplication
- Simplify conditionals
- Introduce abstractions
- Improve error handling

Best Practices

1. Clear Purpose

Define a focused purpose for each agent:

---
name: api-designer
description: Specialized in designing RESTful APIs and API documentation
---

You are an API design specialist...

2. Appropriate Tools

Only grant tools the agent actually needs:

tools:
  - Read      # To read existing API code
  - Write     # To create API definitions
  - Grep      # To search for patterns
# No Bash - API designer doesn't need shell access

3. Structured Prompts

Organize the system prompt with clear sections:

## Role Definition
[Who the agent is]

## Expertise
[What they're good at]

## Approach
[How they work]

## Guidelines
[Rules to follow]

## Output Format
[How to present results]

4. Model Selection

Choose appropriate models:

modelConfig:
  model: qwen3-coder-plus    # For coding tasks
  # model: qwen3-coder        # For simpler tasks
  temperature: 0.3             # Lower for precise work
  # temperature: 0.7           # Higher for creative work

5. Task Examples

Include examples in the prompt:

## Example Tasks

**Input**: "Review this function for security issues"
**Output**: Provide analysis with:
1. Security vulnerabilities found
2. Severity ratings
3. Recommended fixes
4. Prevention strategies

Using Agents

Once installed, users access agents through:

/agents manage

This opens the agent manager where they can:

Browse available agents
See agent descriptions and capabilities
Select an agent to start a conversation
Switch between agents

Agent Discovery

Extension agents appear in the agent manager under “Extension Agents” section, separate from user-defined agents.

Multiple Agents

You can include multiple agents in one extension:

dev-tools-extension/
├── qwen-extension.json
└── agents/
    ├── code-reviewer.md
    ├── test-writer.md
    ├── debugger.md
    ├── documenter.md
    └── refactorer.md

Each serves a different purpose in the development workflow.

Agent vs Skill

When to use an Agent:

User explicitly invokes it
Complex, multi-step workflows
Needs conversation context
Requires human input/decisions

When to use a Skill:

AI automatically invokes it
Specialized capability
Single-purpose function
No human interaction needed

Next Steps

Creating Extensions - Build a complete extension
Skills - Create AI-invoked capabilities
Commands - Add custom commands
Best Practices - Extension development guidelines

Documentation Index

​Creating Agent Extensions

​What are Subagents?

​Agent File Format

​Frontmatter Fields

​Available Tools

​Extension Structure

​Configure in Manifest

​Example: Diary Writer Agent

​Example: Test Writer Agent

​Example: Refactoring Expert

​Best Practices

​1. Clear Purpose

​2. Appropriate Tools

​3. Structured Prompts

​4. Model Selection

​5. Task Examples

​Using Agents

​Agent Discovery

​Multiple Agents

​Agent vs Skill

​Next Steps