Skip to main content

Skills vs Agents

SpecWeave uses two types of AI components: Skills (auto-activating knowledge) and Agents (explicitly invoked workers). Understanding the difference is crucial for effective use.

Quick Comparison​

AspectSkillsAgents
ActivationAutomatic (keywords)Explicit (Task() call)
ContextMain conversationSub-agent (isolated)
PurposeProvide knowledge/guidanceExecute complex tasks
OutputInline responseFinal report
FileSKILL.mdAGENT.md

Skills​

Skills are knowledge modules that activate automatically when relevant keywords appear in conversation.

How They Work​

Characteristics​

  • Auto-activate: No explicit command needed
  • Main context: Runs in current conversation
  • Knowledge-focused: Provide information, not execute tasks
  • Lightweight: ~2-5K tokens typically

Example Skills​

specweave:increment-planner    # Activates for "plan increment"
specweave:brownfield-analyzer  # Activates for "existing project"
specweave:tdd-workflow         # Activates for "TDD", "red-green"
specweave:serverless-recommender  # Activates for "serverless", "Lambda"

Skill File Structure​

---
name: increment-planner
description: Creates implementation plans for SpecWeave increments.
             Activates for: increment planning, feature planning,
             hotfix, MVP, new product.
---

# Increment Planner

## When to Activate
[Keywords and scenarios...]

## How to Use
[Guidance and templates...]

Agents​

Agents are specialized workers that execute complex tasks in isolated sub-contexts.

How They Work​

Characteristics​

  • Explicitly invoked: Via Task() tool or commands
  • Isolated context: Separate from main conversation
  • Task-focused: Execute and produce output
  • Heavyweight: Can use 10-50K tokens

Example Agents​

specweave:pm:pm              # Product management
specweave:architect:architect # System architecture
specweave:tech-lead:tech-lead # Technical implementation
specweave:qa-lead:qa-lead     # Quality assurance

Agent File Structure​

---
name: pm-agent
description: Product Manager AI agent for strategy, requirements,
             user stories. Activates explicitly via Task().
---

# PM Agent

## Capabilities
[What the agent can do...]

## Workflow
[Step-by-step process...]

## Output Format
[Expected deliverables...]

When to Use Which​

Use Skills When:​

  • Need information or guidance
  • Want auto-activation on keywords
  • Response should be inline
  • Task is advisory, not generative

Examples:

  • "How do I handle brownfield projects?" → brownfield-analyzer skill
  • "What's the TDD workflow?" → tdd-workflow skill
  • "Which serverless platform?" → serverless-recommender skill

Use Agents When:​

  • Need to generate complex output
  • Task requires isolated context
  • Multiple files need creation
  • Heavy computation needed

Examples:

  • Generate spec.md → pm agent
  • Design architecture → architect agent
  • Create infrastructure → devops agent

Context Management​

Skills: Shared Context​

Main Context (100K tokens)
├── User conversation
├── Skill 1 (loaded, 3K)
├── Skill 2 (loaded, 2K)
└── Response

Agents: Isolated Context​

Main Context (100K tokens)
├── User conversation
├── Task() call
│   └── Agent Context (separate)
│       ├── Agent instructions
│       ├── Relevant files
│       └── Generated output
└── Agent report returned

Best Practices​

Skills​

DO:

  • Keep skills focused and small
  • Use clear activation keywords
  • Provide templates and examples

DON'T:

  • Spawn agents from skills (context explosion!)
  • Make skills too generic
  • Include heavy computation

Agents​

DO:

  • Use for multi-step generation
  • Keep context isolated
  • Return clear reports

DON'T:

  • Spawn multiple agents in parallel for large tasks
  • Use agents for simple questions
  • Skip quality gates