Skip to content

Skills and Specs

Rules files (AGENTS.md) provide static context that loads every session. Skills and specs are two additional types of file-based memory that load on demand.

Skills: Procedural Memory

Rules files have a scaling problem: everything loads every time. A 500-line deployment procedure consumes tokens whether you're deploying or writing unit tests.

Skills solve this through progressive disclosure. Only skill metadata loads at startup. Full instructions load when invoked.

project/
├── AGENTS.md           # Always loaded (~500 tokens)
└── .skills/
    ├── deploy/
    │   └── SKILL.md    # Loads only when deploying
    └── review/
        └── SKILL.md    # Loads only when reviewing

Think of skills as procedural memory: knowledge about how to do things, stored separately from facts about the project.

For skill format and design principles, see Agent Skills.

Specs: Requirements Memory

When you describe a feature in conversation, the agent understands it for that session. Tomorrow, in a new session, you'd have to explain again.

A spec file persists requirements:

# Feature: User Authentication

## Requirements

- Users can sign up with email/password
- Sessions expire after 24 hours of inactivity
- Failed login attempts are rate-limited

## Acceptance Criteria

- [ ] Sign up creates new user record
- [ ] Sign in returns JWT token
- [ ] Rate limit triggers after 5 failures

The agent reads the spec, implements against it, and checks off criteria as it goes. Work can resume across sessions without re-explanation.

Think of specs as declarative memory: what needs to be built rather than how to build it.

Three Types of File Memory

Type Contains Loading Analogy
Rules (AGENTS.md) Facts, conventions, vocabulary Always Semantic memory
Skills (SKILL.md) Procedures, workflows On-demand Procedural memory
Specs Requirements, acceptance criteria On-demand Declarative goals

When to Use What

Rules hold project conventions, domain vocabulary, navigation hints, and command syntax - anything that applies broadly.

Skills are for multi-step procedures like deployment or release workflows. Use them when instructions are longer than a few hundred tokens or don't apply to every task.

Specs capture feature requirements and acceptance criteria, especially for work that spans multiple sessions.

For guidance on rules content, see Agent Rules.