Specialist Agent

Supercharge Claude Code with specialized AI agents for any framework.
Scaffold projects, build features, review architecture, migrate legacy code, and hunt bugs — all following your project's conventions automatically.

What is Specialist Agent?

Specialist Agent is a collection of AI agents, skills, and architectural conventions for Claude Code. It's not a library — it's a set of markdown instructions that make Claude Code work like a senior developer who knows your codebase.

Framework packs provide stack-specific agents, skills, and architecture patterns:

Token Consumption Notice

Agents consume tokens proportional to their complexity. Specialist Agent ships with Lite agents that use model: haiku — significantly cheaper per token.

Quick Start

1. Install into your project

cd /path/to/your-project
npx specialist-agent init

The wizard asks:

1. Which framework? (Vue 3, React...)
2. Full or Lite mode?
3. Install @starter agent?

2. Start using

claude

# Create a new project from scratch
"Use @starter to create a task-manager app with Vue + Express + PostgreSQL"

# Build a feature inside an existing project
"Use @builder to create an orders module with CRUD for GET/POST/PATCH/DELETE /v2/orders"

Meet Your AI Team

Framework-Agnostic

Specialist Agents

Day-to-Day Development

Architecture Migration

# Start a new full-stack project
"Use @starter to create an e-commerce app with Vue + Fastify + PostgreSQL"

# Explore an unfamiliar codebase
"Use @explorer to assess this project — I just joined the team"

# Build features
"Use @builder to create the orders module with CRUD for /v2/orders"

# Review before merging
"Use @reviewer to review the changes in the payments module"

# Debug issues
"Use @doctor to investigate the 500 error on login"

# Migrate legacy code (6 phases with approval gates)
"Use @migrator to migrate the billing module from Options API to script setup"

Skills

Quick shortcuts you invoke with /skill-name in Claude Code.

Development

Quality

Migration

Documentation

Architecture

All agents enforce the four-layer architecture defined in each pack:

Service (HTTP only) → Adapter (parse) → Orchestration → Component (UI)

Each pack adapts the orchestration layer:

Full guide: docs/ARCHITECTURE.md — the source of truth that all agents read.

Lite Mode — Lower Token Usage

For cost-conscious usage or simpler tasks:

npx specialist-agent init    # select "Lite" mode in wizard

Project Structure

specialist-agent/
├── packs/
│   ├── vue/                  ← Vue 3 pack
│   ├── react/                ← React pack
│   ├── nextjs/               ← Next.js pack
│   └── svelte/               ← SvelteKit pack
│       ├── agents/           ← Full agents (4)
│       ├── agents-lite/      ← Lite agents (4)
│       ├── skills/           ← Skills (12)
│       ├── ARCHITECTURE.md   ← Architecture patterns
│       └── CLAUDE.md         ← Pack-specific config
│
├── agents/                   ← Framework-agnostic agents (9 + 9 lite)
│
├── cli/                      ← CLI installer
│   └── index.mjs             ← npx specialist-agent init
│
├── docs/                     ← VitePress documentation
└── package.json

Optional: Context7 MCP

For up-to-date library documentation when asking Claude about APIs, you can add the Context7 MCP server. This benefits you as a developer — agents work fully without it.

Setup

Add to your Claude Code MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Customization

Add an Agent

Create .claude/agents/my-agent.md following the 5-part blueprint (Mission, Workflow, Output, Rules, Handoff):

---
name: my-agent
description: "MUST BE USED to [do X] when [trigger]. Use PROACTIVELY when [condition]."
tools: Read, Write, Edit, Bash, Glob, Grep
---

# Title

## Mission
One sentence describing what this agent does.

## Workflow
1. Step one
2. Step two

## Output
After completing work, provide:
- What was done (files created/modified)
- Key decisions and rationale
- Validation results
- Recommendations for next steps

## Rules
- Rule one
- Rule two

## Handoff Protocol
- If [condition] → suggest @agent-name

Add a Skill

Create .claude/skills/my-skill/SKILL.md:

---
name: my-skill
description: "What this skill does and when to use it"
user-invocable: true
argument-hint: "[arguments]"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

Instructions for the skill.

Target: $ARGUMENTS

## Steps
1. ...

Edit Architecture Patterns

Edit docs/ARCHITECTURE.md — all agents read this file before acting. Changes take effect immediately.

Documentation

Full docs are available via VitePress:

cd specialist-agent
npm install && npm run docs:dev

• Introduction
• Installation
• Quick Start
• Architecture Guide
• Agents Reference
• Skills Reference

Contributing

Contributions are welcome!

• Star this repo if you find it useful
• Issues — Report bugs or suggest improvements
• Pull Requests — New packs, agents, skills, or pattern improvements
• Discussions — Share how you've customized Specialist Agent

git checkout -b feature/my-feature
git commit -m 'feat: add my feature'
git push origin feature/my-feature
# Open a Pull Request

License

MIT — Use freely. See LICENSE.

Built for developers who use Claude Code every day.
GitHub · Docs · Issues