Required Plugins

Superpowers plugin: MUST be active for all work using this skill. Use throughout the entire build pipeline — design decisions, code generation, debugging, quality checks, and any task where it offers enhanced capabilities. If superpowers provides a better way to accomplish something, prefer it over the default approach.

Custom Sub-Agents Skill

Overview

This skill defines the standards and workflow for creating, organizing, and documenting custom sub-agents (AI agents, code assistants, or workflow bots) within the BIRDC ERP project. It ensures that all sub-agents are discoverable, maintainable, and compatible with both GitHub Copilot and Claude in VS Code.

Folder Structure

skills/
└── custom-sub-agents/
	 ├── SKILL.md                ← This skill file (standards, checklist)
	 ├── references/
	 │   └── CUSTOM_SUB_AGENTS_GUIDE.md  ← Reference guide
	 └── [agent folders]/        ← One folder per sub-agent
		  ├── agent-name/
		  │   ├── agent.js|php|py|ts  ← Agent implementation
		  │   ├── README.md           ← Agent documentation
		  │   └── ...

Requirements

One Folder per Sub-Agent
- Each sub-agent must have its own folder under skills/custom-sub-agents/.
- Folder name: agent-name (kebab-case, descriptive).
Documentation
- Each agent folder must include a README.md describing:
  - Agent purpose and capabilities
  - Usage instructions
  - Configuration (if any)
  - Example prompts or API calls
Entry Point
- The main agent file must be named agent.js, agent.php, agent.py, or agent.ts as appropriate.
- The entry file must export or define a function/class named after the agent (PascalCase).
Reference Guide
- All sub-agents must be listed in references/CUSTOM_SUB_AGENTS_GUIDE.md with a summary and link to their folder.
Compatibility
- Agents must be compatible with both GitHub Copilot and Claude (Anthropic) in VS Code.
- Use only supported APIs and avoid proprietary features unless polyfilled.
Testing
- Each agent must include a test or usage example in its README.md.
Versioning
- Update this SKILL.md and the reference guide when adding, removing, or changing agents.

Technical Implementation & Benefits

File Naming Convention

GitHub Copilot: Recognizes and auto-loads markdown files named agent-name.agent.md
Claude: Compatible with standard markdown documentation
Auto-loading: Context is automatically included in every conversation

Context Window Optimization

Massive Efficiency Gains: Tasks that consumed 80k+ tokens now use <4k tokens
Sustainable Development: Enables complex, multi-step workflows without context bloat
Scalable Architecture: Supports large projects with extensive requirements

Implementation Ease

Self-Implementing: Ask Copilot/Claude to create new sub-agents with desired functionality
Rapid Prototyping: New agents can be created quickly with proper structure
Iterative Development: Easy to enhance and modify existing agents

Skills Integration

Enhanced Capabilities: Combine sub-agents with specialized skills for domain expertise
Modular Architecture: Mix and match agents and skills for specific workflows
Best Practice Patterns: Leverage proven skill frameworks within agent implementations

Use Case Optimization

Big Functional Prompts: Most beneficial for complex feature development
Zero-to-POC Workflows: Excellent for proof-of-concept and prototyping
Simple Fixes: Consider single LLM for basic "fix that error" scenarios
Context-Aware Decisions: Choose sub-agents when context conservation matters

Codebase Analysis & Planning

When to Use Sub-Agents vs Single LLM

Ask the AI Agent to analyze your codebase:

"Analyze my codebase and recommend where sub-agents would be most beneficial.
Consider: code complexity, domain areas, repetitive tasks, integration points,
and context window requirements. Tell me what agents I need, where they should
live, and how they should interact."

Analysis Criteria

Create Sub-Agents For:

Complex Domain Areas
- Multi-step workflows (authentication, payments, inventory)
- Business logic with many edge cases
- Integration with external APIs/services
Repetitive Development Tasks
- Code generation patterns (CRUD operations, API endpoints)
- Testing strategies for specific components
- Documentation generation for modules
Context-Intensive Work
- Large codebases requiring sustained context
- Multi-file refactoring operations
- Complex architectural decisions
Specialized Expertise Areas
- Security implementations
- Performance optimization
- Database schema design
- UI/UX pattern implementation

Use Single LLM For:

Simple bug fixes and error resolution
Code reviews of individual files
Quick refactoring of small functions
Basic code explanations

Planning Your Sub-Agent Architecture

Step 1: Codebase Analysis Prompt

Analyze this codebase structure and identify:
- Key functional areas that could benefit from specialized agents
- Integration points that require consistent handling
- Repetitive patterns that could be automated
- Complex workflows that consume significant context
- Areas where domain expertise would improve outcomes

Step 2: Agent Definition For each identified area, define:

Purpose: What does this agent do?
Scope: What files/code does it handle?
Inputs: What information does it need?
Outputs: What does it produce?
Interactions: How does it work with other agents?

Step 3: Implementation Planning

File Structure: Where will the agent live?
Dependencies: What tools/utilities does it need?
Testing: How will you validate the agent?
Documentation: How will users discover and use it?

Example Analysis Output

Recommended Sub-Agents:

Database Migration Agent (database-migrations.agent.md)
- Handles schema changes, data migrations, rollback strategies
- Location: skills/custom-sub-agents/database-migrations/
API Development Agent (api-development.agent.md)
- Generates REST endpoints, validates requests, handles errors
- Location: skills/custom-sub-agents/api-development/
UI Component Agent (ui-components.agent.md)
- Creates reusable components, handles styling, ensures consistency
- Location: skills/custom-sub-agents/ui-components/

Integration Points

Cross-Agent Communication:

Define clear interfaces between agents
Establish data sharing protocols
Create shared utilities and helpers
Document agent dependencies and workflows

Context Management:

Identify shared context requirements
Plan for context handoffs between agents
Optimize for minimal context overlap
Design for resumable workflows

VS Code Integration & Enforcement Checklist

Register agent folder in references/CUSTOM_SUB_AGENTS_GUIDE.md
Ensure agent entry file and README.md exist
Confirm agent is discoverable by Copilot/Claude (test in VS Code)
Add usage example in README.md
Enable sub-agent support in VS Code settings:
- Add the following to your .vscode/settings.json:
```
{
  "chat.customAgentInSubagent.enabled": true
}
```
- This setting is required for both GitHub Copilot and Claude to use custom sub-agents in the latest VS Code Insiders build.

Example Agent Folder

skills/custom-sub-agents/
└── smart-approver/
	 ├── agent.js
	 ├── README.md

Last Updated

30 January 2026

custom-sub-agents