Generates Custom Agent files (.github/agents/*.agent.md) with persona-based configurations, specialized tool sets, and role-specific cognitive architectures. Use when the user requests a specialized role or perspective (Security Auditor, Documentation Writer, Release Engineer, etc.). Creates agents with defined identity, constrained tools, and thinking processes aligned to their role. Not for general capabilities—use generate-agent-skills for those.
Generates Custom Agent files (.github/agents/*.agent.md) with persona-based configurations, specialized tool sets, and role-specific cognitive architectures. Use when the user requests a specialized role or perspective (Security Auditor, Documentation Writer, Release Engineer, etc.). Creates agents with defined identity, constrained tools, and thinking processes aligned to their role. Not for general capabilities—use generate-agent-skills for those.
Custom Agent Generator (Persona Factory)
Overview
This skill generates Custom Agent files that act as persistent specialized roles with:
NO write tools: Reports findings, doesn't fix (stays in audit role)
Documentation Writer:view, grep, create, edit
Rationale: Reads existing docs, creates new docs, updates content
YES write tools: Primary job is creating/maintaining documentation
Step 4: Cognitive Architecture Design
Goal: Define how this agent thinks (role-specific reasoning process).
Load cognitive architecture patterns:
cat references/cognitive_architecture_patterns.md
Design the <thinking_process> based on role:
Components:
Initial Assessment - How does agent approach a new request?
Domain-Specific Analysis - What does agent look for first?
Constraint Application - What rules/principles guide thinking?
Decision Criteria - How does agent prioritize/evaluate?
Output Formulation - How does agent structure responses?
Example thinking processes:
Security Auditor:
<thinking_process>
1. **Threat Model First:** What could go wrong? What's the attack surface?
2. **Assume Breach Mindset:** If an attacker had access, what could they do?
3. **Check Common Vulnerabilities:** SQL injection, XSS, auth bypass, secrets exposure
4. **Trace Data Flow:** Where does user input flow? Is it sanitized?
5. **Prioritize by Impact:** Critical > High > Medium > Low severity
6. **Report with Evidence:** Include code snippets, line numbers, exploitation scenarios
</thinking_process>
Documentation Writer:
<thinking_process>
1. **Audience First:** Who will read this? What's their knowledge level?
2. **Information Architecture:** How does this fit in existing docs structure?
3. **Clarity over Cleverness:** Simple, direct language. Avoid jargon.
4. **Show, Don't Tell:** Include examples, code snippets, screenshots
5. **Style Consistency:** Follow established voice, tone, formatting
6. **Completeness Check:** Did I answer what/why/how? Include edge cases?
</thinking_process>
Step 5: Template Population
Goal: Generate the agent file using the template.
Load agent template:
cat assets/agent_template.md
Populate these sections:
YAML Frontmatter:
name: kebab-case role name (e.g., security-auditor)
description: One-sentence summary of role and purpose
tools: Array of tool names (validated in Step 3)
Agent Identity:
Role title and expertise domain
What makes this agent special
When to use this agent vs default
Thinking Process:
Role-specific <thinking_process> from Step 4
Structured with XML delimiters (prevents system prompt leakage)
✅ Created: .github/agents/{{agent-name}}.agent.md
🎭 Role: {{Job Title}}
🛠️ Tools: {{tool1, tool2, tool3}}
💡 Unique Value: {{one-sentence value prop}}
📖 To use: Reference this agent in your request or switch to it in VS Code
Step 7: Usage Guidance (Optional)
Help the user understand how to use their new agent:
Activation methods:
Explicit request: "Use the security-auditor agent to review this code"
VS Code switcher: Select agent from dropdown
Auto-matching: Agent activates based on task keywords (if configured)
Best practices:
Use for tasks that benefit from the role's perspective
Don't overuse—default agent is fine for general tasks
Combine with skills for powerful workflows (e.g., Security Auditor + generate-tests)
Resources
references/role_analysis_checklist.md
Guides LLM through defining agent identity, expertise, and perspective.
references/tool_selection_guide.md
Decision framework for choosing agent tools with security constraints.
references/cognitive_architecture_patterns.md
Examples of role-specific thinking processes for common agent types.
assets/agent_template.md
Complete agent file template with XML delimiters and structure.
