Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Skills

Skills are knowledge, not actors. They provide patterns, documentation, and procedures that agents use to perform tasks. Think of skills as technical manuals that agents consult.

Skills vs Agents

  • Skills = Knowledge (how to do something)
  • Agents = Actors (does the work)

Example: The validation skill contains knowledge about running tests, type checking, and linting. The reviewer agent uses this skill to actually validate code.

Three-Tier Architecture

Like agents, skills are organized into three categories:

  1. Core Skills (included) - Universal knowledge like validation, testing, research. Same for all projects.
  2. Domain Skills (generated) - Tech-specific knowledge like Next.js patterns, Prisma schemas, Tailwind conventions. Created by Architect based on your codebase.
  3. Ephemeral Skills (temporary) - Task-specific knowledge for one-off tasks or longer-term work, then removed when done (migration-procedures for a 2-hour task, legacy-api-docs for a multi-week migration).

Skills are shared across all agents - any agent can reference any skill. See our philosophy for details.

Core Skills

SkillKnowledge ProvidedUsed By
conversationIntent classification, context management patterns/agentful command
DeploymentDeployment procedures, production readiness checksOrchestrator, deployment workflows
product-planningSpecification analysis, gap identification/agentful-product, product-analyzer
product-trackingProgress calculation methods, state tracking/agentful-status, orchestrator
researchBest practices research via Context7/WebSearch/agentful-generate, orchestrator
testingTest strategy, coverage optimizationTester agent, reviewer agent
validationQuality gate checks, tool detection/agentful-validate, reviewer

Domain Skills

Domain skills are tech-specific knowledge (Next.js, Prisma, Tailwind, etc.) generated from your codebase using:

/agentful-generate

This analyzes your project and creates skills containing:

  • Framework patterns detected in your code
  • Tech stack conventions you're using
  • Project-specific architectural decisions
Examples:
  • .claude/skills/nextjs-patterns/ - App Router, Server Components, Server Actions
  • .claude/skills/prisma-schemas/ - Models, migrations, relations
  • .claude/skills/tailwind-conventions/ - Design system, spacing, colors

These generated skills ensure agents follow your existing patterns instead of imposing generic templates.

Ephemeral Skills

Temporary skills for one-off tasks (hours) or longer-term work (weeks/months), then deleted:

Examples:
  • db-migration/ - Procedures for a 2-hour PostgreSQL to MySQL migration
  • legacy-api-docs/ - Documentation for old API during multi-week migration
  • performance-profiling/ - Profiling procedures during optimization work

Create in .claude/skills/ephemeral/ and delete when the task is complete.

Skill Structure

Each skill is a Markdown file at .claude/skills/<skill-name>/SKILL.md:

---
name: skill-name
description: What this skill provides
model: sonnet
tools: Read, Write, Edit, Bash
---
 
# Skill Name
 
## Knowledge Provided
What information this skill contains
 
## Usage Patterns
How agents should use this knowledge
 
## Examples
Concrete examples of applying this skill

How Agents Use Skills

  1. Agent receives a task
  2. Agent checks relevant skills for patterns/procedures
  3. Agent applies knowledge to execute the task
  4. Agent updates state using skill-defined structures

Example flow:

User: /agentful add authentication
 
1. conversation skill → classifies intent as "feature_request"
2. orchestrator agent → reads product-tracking skill for progress tracking
3. backend agent → uses generated Express skill for implementation patterns
4. reviewer agent → applies validation skill to check quality

Custom Skills

Create custom skills in .claude/skills/:

.claude/skills/
├── staging-workflow/
│   └── SKILL.md
└── monitoring/
    └── SKILL.md

Example custom skill:

---
name: staging-workflow
description: Custom staging deployment workflow for our infrastructure
model: sonnet
tools: Read, Bash
---
 
# Staging Workflow Skill
 
## Deployment Targets
- Staging: Vercel Preview
- Pre-production: AWS ECS
- Demo: Netlify
 
## Pre-deployment Checklist
1. All tests passing
2. Type checking clean
3. Environment variables set
4. Database migrations applied
 
## Deployment Commands
\`\`\`bash
# Deploy to staging
npm run deploy:staging
 
# Deploy to pre-production
npm run deploy:preprod
\`\`\`
 
## Rollback Procedure
\`\`\`bash
npm run rollback:staging -- --version <previous-version>
\`\`\`

Agents will reference this skill when deploying your application.

Next Steps