# Agent Development

> Agent development for Copilot CLI plugins: .agent.md files, agent frontmatter, system prompts, triggering conditions, tool restrictions, model selection. Use when creating, configuring, or debugging autonomous agents.

- **Type:** Skill
- **Install:** `agentstack add skill-poorgramer-zack-copilot-cli-things-agent-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Poorgramer-Zack](https://agentstack.voostack.com/s/poorgramer-zack)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Poorgramer-Zack](https://github.com/Poorgramer-Zack)
- **Source:** https://github.com/Poorgramer-Zack/copilot-cli-things/tree/main/plugins/plugin-dev/skills/agent-development

## Install

```sh
agentstack add skill-poorgramer-zack-copilot-cli-things-agent-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent Development for Copilot CLI Plugins

Create autonomous agents (.agent.md) that handle complex, multi-step tasks independently. Define structure, triggering conditions, and system prompts.

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

## Agent File Structure

### Complete Format

```markdown
---
description: Use this agent when [triggering conditions].
model: claude-sonnet-4.5
tools: [read, edit, 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]
```

## Frontmatter Fields

### description (required)

Defines when Copilot should trigger this agent. **This is the most critical field.**

**Must include:**
1. Triggering conditions ("Use this agent when...")
2. Context describing when agent is appropriate

**Format:**
```
Use this agent when [conditions].
```

**Best practices:**
- Be specific about triggering conditions
- Cover different phrasings of same intent
- Be specific about when NOT to use the agent

### model (optional)

Which model the agent should use.

**Options:**
- `claude-sonnet-4.5` - Claude Sonnet (balanced, default)
- `claude-opus-4.5` - Claude Opus (most capable, expensive)
- `claude-haiku-4.5` - Claude Haiku (fast, cheap)

**Recommendation:** Omit unless agent needs specific model capabilities. Defaults to session model.

### tools (optional)

Restrict agent to specific tools.

**Format:** Array of tool names (lowercase, unquoted)

```yaml
tools: [read, edit, grep, powershell]
```

**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, edit, grep]`
- Testing: `[read, powershell, grep]`
- Full access: Omit field

## System Prompt Design

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

### Structure

**Standard template:**
```markdown
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 Copilot CLI):

```
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
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3  blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: ...",
  "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 omit for default)
4. Define tools (if restricting access)
5. Write system prompt with structure above
6. Save as `agents/agent-name.agent.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.agent.md
    ├── reviewer.agent.md
    └── generator.agent.md
```

All `.agent.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 conditions
2. Use similar phrasing in test
3. Check Copilot 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

```markdown
---
description: Use this agent when...
model: claude-sonnet-4.5
---

You are an agent that [does X].

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

Output: [What to provide]
```

### Frontmatter Fields Summary

| Field | Required | Format | Example |
|-------|----------|--------|---------|
| description | Yes | Text | Use when... |
| model | No | model name | claude-sonnet-4.5 |
| tools | No | Array of tool names | [read, grep] |

### Best Practices

**DO:**
- ✅ Include concrete triggering conditions in description
- ✅ Write specific triggering conditions
- ✅ Omit model field unless specific need
- ✅ Choose appropriate tools (least privilege)
- ✅ Write clear, structured system prompts
- ✅ Test agent triggering thoroughly

**DON'T:**
- ❌ Use generic descriptions
- ❌ Omit triggering conditions
- ❌ 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 Copilot CLI

### 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.agent.md` file
4. Write frontmatter with required fields
5. Write system prompt following best practices
6. Include triggering conditions in description
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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Poorgramer-Zack](https://github.com/Poorgramer-Zack)
- **Source:** [Poorgramer-Zack/copilot-cli-things](https://github.com/Poorgramer-Zack/copilot-cli-things)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-poorgramer-zack-copilot-cli-things-agent-development
- Seller: https://agentstack.voostack.com/s/poorgramer-zack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.