Skills & Agents Architecture

Skills and custom agents are the extension mechanisms of AI coding agents. Skills provide on-demand domain knowledge, while custom agents provide specialized capabilities with isolated context.

Skills: On-Demand Knowledge

What Skills Are

Skills are markdown files that the AI agent loads when relevant — not every session. This is the key difference from agent configuration files: skills don’t consume context until needed.

Store skills in a directory dedicated to agentic infrastructure. See Tool Configuration Reference for where your specific tool expects skill files.

When to Use Agent Configuration Files vs. Skills

Use Agent Configuration Files	Use Skills
Build commands	API design conventions
Project architecture overview	Database migration patterns
Universal coding conventions	Deployment procedures
Testing commands	Code review checklists
Things needed EVERY session	Things needed SOME sessions

Creating Effective Skills

The content structure below applies regardless of where your tool stores skill files. See Tool Configuration Reference for your tool’s specific path convention.

.agents/skills/api-conventions/skill.md

---
name: api-conventions
description: REST API design conventions for our services
---

# API Conventions

## Endpoint Structure
- Use kebab-case for URL paths: `/api/user-profiles`
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path: `/v1/`, `/v2/`

## Response Format
All responses use this envelope:
```json
{
  "data": {},
  "error": null,
  "meta": { "requestId": "...", "timestamp": "..." }
}

Authentication

• Bearer token in Authorization header
• Token validation in src/middleware/auth.ts
• Role-based access via src/middleware/rbac.ts

Error Codes

• 400: Validation error (include field-level details)
• 401: Missing or invalid token
• 403: Valid token, insufficient permissions
• 404: Resource not found
• 429: Rate limited (include Retry-After header)

### Invocable Skills (Workflows)

Some tools support skills that function as explicit, invocable workflows rather than passive context. Claude Code calls these "commands" and activates them with a leading `/`; other tools may use different conventions.

```markdown
# .agents/skills/fix-issue/skill.md
---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true
---

Fix the GitHub issue: $ARGUMENTS

1. Use `gh issue view $ARGUMENTS` to get issue details
2. Research the relevant codebase area using sub-agents
3. Create a plan in .sdlc/plans/issue-$ARGUMENTS.md
4. Write failing tests that reproduce the issue
5. Implement the fix with minimum code changes
6. Run full test suite and verify
7. Run typecheck and lint
8. Create a descriptive commit
9. Push and create PR with `gh pr create`

Invoke with: /fix-issue 1234

Custom Sub-Agents: Specialized Context

Why Custom Agents Matter

Sub-agents run in their own context window with their own tool permissions. This provides:

• Context isolation — exploration doesn’t pollute the main agent’s conversation
• Specialization — agents with focused instructions outperform generalists
• Parallelism — multiple agents can work simultaneously

Agent Definition

Agent definitions are markdown files stored in your agentic infrastructure directory. See Tool Configuration Reference for your tool’s specific path. Each file describes one specialized agent.

.agents/agents/security-reviewer.md

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
# model: specify a cost-efficient model for read-only review tasks
---

You are a senior security engineer. Review code for:

## Checklist
- [ ] Injection vulnerabilities (SQL, XSS, command injection)
- [ ] Authentication and authorization flaws
- [ ] Secrets or credentials in code
- [ ] Insecure data handling (PII exposure, missing encryption)
- [ ] CSRF protection on state-changing endpoints
- [ ] Rate limiting on sensitive endpoints

## Output Format
For each finding:
1. Severity: Critical / High / Medium / Low
2. File and line number
3. Description of the vulnerability
4. Suggested fix with code example

Agent with Worktree Isolation

For agents that modify code, use worktree isolation:

.agents/agents/feature-implementer.md

---
name: feature-implementer
description: Implements features in an isolated worktree
tools: Read, Write, Edit, Bash, Grep, Glob
# model: specify a more capable model for complex implementation tasks
isolation: worktree
---

Implement the feature described in the task.

## Workflow
1. Read the spec/plan if one exists
2. Write failing tests first
3. Implement minimum code to pass tests
4. Run full test suite
5. Run typecheck and lint
6. Commit changes with descriptive message

## Rules
- Follow existing code patterns
- Never modify test infrastructure
- Keep changes focused on the specified feature

Tip

With worktree isolation, each agent gets a complete copy of the codebase. Agent A can rewrite src/auth.ts while Agent B rewrites the same file — changes are reconciled when worktrees merge back.

Agent Best Practices

Practice	Reason
Limit tools to what’s needed	Reduces attack surface and accidental damage
Specify a smaller/faster model for review tasks	Cheaper for read-only analysis with no quality loss
Specify a more capable model for complex implementation	Better reasoning for hard problems justifies the cost
Keep agent instructions focused	Specialized agents outperform generalists
Limit to 3-4 active worktrees	More causes management overhead and memory bloat

Architecture Patterns

Writer-Reviewer Pattern

Session A (Writer)                    Session B (Reviewer)
───────────────────                   ────────────────────
Implement rate limiter
   └─→ creates src/middleware/rateLimit.ts
                                      Review rate limiter in
                                      src/middleware/rateLimit.ts
                                      Look for edge cases, race
                                      conditions, consistency
                                         └─→ returns feedback
Address review feedback
from Session B

Research-Implement Pattern

Main Agent (Orchestrator)
├── Sub-Agent: Research auth system → returns summary
├── Sub-Agent: Research rate limiting patterns → returns summary
│
├── [Human reviews research summaries]
│
├── Main Agent: Creates implementation plan
│
├── [Human reviews plan]
│
└── Sub-Agent (worktree): Implements plan → returns diff

Parallel Implementation Pattern

Main Agent: Creates implementation plan with 3 independent tasks
├── Agent (worktree-1): Implements Task A
├── Agent (worktree-2): Implements Task B
└── Agent (worktree-3): Implements Task C
    └── All merge back via git