Documentation > Features > Skills vs Agents vs Teams

skill-creator organizes AI capabilities at three levels of abstraction: skills (individual knowledge units), agents (composed specialists), and teams (coordinated groups). Understanding when to use each — and how they compose — is key to building effective AI-assisted workflows.

At a Glance

Level	What It Is	Scope	Example
Skill	A single knowledge unit with triggers	One concern	beautiful-commits — commit message formatting
Agent	A composed specialist combining skills	One role	typescript-quality — combines typescript-patterns + test-generator + code-review
Team	A coordinated group of agents	One project/task	GSD Debugging Team — 3 agents investigating hypotheses in parallel

Skills: The Atomic Unit

A skill is a single SKILL.md file with YAML metadata and markdown body:

# .claude/skills/beautiful-commits/SKILL.md
---
name: beautiful-commits
description: Crafts professional git commit messages following Conventional Commits
user-invocable: true
allowed-tools: [Bash, Read, Glob, Grep]
metadata:
  extensions:
    gsd-skill-creator:
      enabled: true
      triggers:
        - pattern: "\\b(commit|git commit)\\b"
          confidence: 0.8
        - keywords: [commit, message, conventional]
          confidence: 0.6
---

# Beautiful Commits

## Format
<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
Subject: <72 chars, lowercase, imperative mood, no period
Body: Explain WHY/WHAT, not HOW. Wrap at 72 chars.

Key properties:

• Auto-triggered — Loaded when session context matches trigger patterns
• Budget-aware — Each skill consumes context tokens (tracked via /sc:status)
• Refinable — Improves from your corrections over time (bounded: max 20% change, 7-day cooldown)
• Scoped — Project-level (.claude/skills/) or user-level (~/.claude/skills/)

Agents: Composed Specialists

An agent combines multiple skills into a role-focused specialist with its own tool access and model assignment:

# .claude/agents/typescript-quality.md
---
name: typescript-quality
description: TypeScript code quality specialist combining patterns,
  testing, and review
tools: Read, Write, Bash, Glob, Grep
model: sonnet
---

<role>
You are a TypeScript quality specialist. You combine three capabilities:
1. TypeScript patterns (generics, type narrowing, discriminated unions)
2. Test generation (vitest scaffolds, data factories, mocking)
3. Code review (quality gates, architectural validation)
</role>

<workflow>
1. Analyze the code for TypeScript anti-patterns
2. Generate comprehensive test coverage
3. Review for quality gate compliance
</workflow>

How agents emerge: skill-creator tracks which skills activate together. After 5+ co-activations over 7+ days, it suggests composing them into an agent:

# Co-activation tracker detects cluster:
npx skill-creator agent suggest

# Output:
# Cluster: [typescript-patterns, test-generator, code-review]
# Co-activations: 12 over 14 days
# Suggested agent: typescript-quality

Teams: Coordinated Groups

A team coordinates multiple agents working on a shared task with defined topology:

// .claude/teams/feature-build.json
{
  "name": "feature-build",
  "topology": "leader-worker",
  "members": [
    {
      "name": "architect",
      "role": "orchestrator",
      "model": "opus",
      "tools": ["Read", "Write", "Edit", "Bash", "Task"]
    },
    {
      "name": "implementer",
      "role": "executor",
      "model": "sonnet",
      "tools": ["Read", "Write", "Edit", "Bash"]
    },
    {
      "name": "tester",
      "role": "verifier",
      "model": "sonnet",
      "tools": ["Read", "Bash", "Glob", "Grep"]
    }
  ]
}

5 team topologies:

• Leader-Worker — One coordinator dispatches to workers
• Pipeline — Sequential stages (research → plan → execute → verify)
• Swarm — Homogeneous workers on same task type
• Router — Intelligent dispatcher to specialists
• Map-Reduce — Parallel processing with aggregation

The Composition Hierarchy

Team (coordinated group)
  └─ Agent (composed specialist)
       └─ Skill (atomic knowledge unit)
            └─ Triggers (when to activate)
            └─ Body (what to do)
            └─ References (supporting material)

Example:
  GSD Debugging Team
    └─ hypothesis-agent (investigates theory A)
    │    └─ typescript-patterns skill
    │    └─ code-review skill
    └─ hypothesis-agent (investigates theory B)
    │    └─ typescript-patterns skill
    │    └─ test-generator skill
    └─ synthesizer-agent (reconciles findings)
         └─ decision-framework skill

Real-World Comparison: Brainstorm vs. OpenStack

Two systems that use all three levels differently:

Aspect	Brainstorm (v1.32)	OpenStack (v1.33)
Skills	16 technique skills (freewriting, SCAMPER, Six Hats, etc.)	19 service skills (Keystone, Nova, Neutron, etc.)
Agents	8 agents (Facilitator, Ideator, Critic, etc.)	31 agents across 3 crews
Team	Single session team with 4-loop bus	3 crews (Deployment, Operations, Documentation)
Topology	Router (Facilitator routes to technique agents)	Leader-Worker per crew, Pipeline across crews
Gating	Critic gated to Converge phase	118 pre-deploy validation checks
Communication	4 loops (session, capture, user, energy)	9 loops with priority-based bus arbitration

When to Use What

Situation	Use	Why
Single repeating pattern	Skill	Lightweight, auto-triggered, minimal overhead
Multiple related patterns	Agent	Unified context, reduced loading overhead
Complex multi-step task	Team	Parallel execution, specialized roles
GSD phase execution	Team (automatic)	GSD creates teams for wave-based execution
Quick one-off task	Skill or nothing	Don't over-engineer small tasks