tutorial

/tutorial - Interactive Tutorial

Learn Specialist Agent with hands-on exercises.

Level: $ARGUMENTS (default: beginner)

---

Beginner Tutorial

Step 1: Your First Agent

Agents are AI specialists. Each one does something specific.

Try this:

Create a Button component with label and onClick props

@builder will create the component following your project's patterns.

What happened:

• @builder read your ARCHITECTURE.md
• Created the component in the right folder
• Added TypeScript types
• Followed your naming conventions

---

Step 2: Review Code

Now review what was created.

Try this:

Review the Button component

@reviewer checks:

1. Does it meet requirements?
2. Is the code clean?
3. Does it follow architecture patterns?

---

Step 3: Use Skills

Skills are shortcuts. They start with /.

Try this:

/health

This shows your project's health score.

Other useful skills:

• /plan - Plan a feature
• /checkpoint - Save your progress
• /remember - Save a decision

---

Step 4: Debug an Issue

When something breaks:

Try this:

Debug why the login button doesn't work

@debugger will:

1. Gather evidence
2. Analyze the code
3. Find the root cause
4. Suggest a fix

---

Beginner Complete

You learned:

• How to use @builder to create code
• How to use @reviewer to check quality
• How to use skills for quick actions
• How to use @debugger to fix issues

Next: Try /tutorial intermediate

---

Intermediate Tutorial

Step 1: Planning Complex Features

For big features, plan first.

Try this:

/plan add user authentication with login and registration

@planner will:

1. Assess complexity
2. Break into tasks
3. Estimate effort
4. Ask for approval

---

Step 2: Test-Driven Development

Write tests first with @tdd.

Try this:

/tdd implement a calculateDiscount function

The workflow:

1. RED - Write failing test
2. GREEN - Make it pass
3. REFACTOR - Clean up

No code without failing test first.

---

Step 3: Checkpoints

Save progress before risky changes.

Try this:

/checkpoint create before-refactor

If something goes wrong:

/checkpoint restore before-refactor

---

Step 4: Session Memory

Remember decisions across sessions.

Save a decision:

/remember use Zustand for state management

Recall later:

/recall state management

---

Step 5: Specialized Agents

Use specialist agents for specific domains.

Agent	Use Case
@api	Design REST/GraphQL APIs
@security	Add authentication
@finance	Payment integration
@perf	Performance optimization
@data	Database design

Try this:

Use @api to design REST endpoints for products

---

Intermediate Complete

You learned:

• Planning with @planner
• TDD with @tdd
• Checkpoints for safety
• Session memory
• Specialist agents

Next: Try /tutorial advanced

---

Advanced Tutorial

Step 1: Agent Composition

Agents can work together.

Example workflow:

1. @planner creates the plan
2. @builder implements each task
3. @reviewer validates the code
4. @tester adds tests

Try this:

Plan and implement a products module with tests

---

Step 2: Custom Agents

Create your own agents.

Command:

npx specialist-agent create-agent @my-agent

Agent structure:

---
name: my-agent
description: "What this agent does"
tools: Read, Write, Edit
---

# @my-agent

## Mission
One sentence describing the goal.

## Workflow
1. First step
2. Second step

## Rules
- Rule one
- Rule two

---

Step 3: Team Profiles

Set behavior for different contexts.

Available profiles:

• startup-fast - Move fast, minimal validation
• enterprise-strict - Full validation, strict rules
• learning-mode - Explain everything
• cost-optimized - Minimize token usage

Set profile:

npx specialist-agent profiles set startup-fast

---

Step 4: Cost Optimization

Reduce token usage:

1. Use Lite mode - 60-80% cheaper
2. Be specific - Less exploration needed
3. Use @scout first - Get recommendations
4. Batch related tasks - Less context switching

Check cost:

/estimate add payment integration

---

Step 5: Multi-Platform

Specialist Agent works on multiple platforms:

Platform	How
Claude Code	Native support
Cursor	.cursor-plugin/
VS Code	.vscode/extension.json
Windsurf	.windsurf/plugin.json

The agents and skills work the same everywhere.

---

Advanced Complete

You learned:

• Agent composition
• Creating custom agents
• Team profiles
• Cost optimization
• Multi-platform usage

---

Quick Reference

Agents

Agent	What it Does
@builder	Build code
@reviewer	Review code
@debugger	Fix bugs
@planner	Plan features
@tdd	Test-driven development
@api	API design
@security	Authentication
@finance	Payments
@perf	Performance

Skills

Skill	What it Does
/plan	Plan a feature
/tdd	TDD workflow
/debug	Debug an issue
/checkpoint	Save/restore progress
/health	Project health score
/remember	Save decisions
/recall	Recall decisions
/estimate	Estimate cost

Documentation

Full docs at: https://specialistagent.com.br/