AI agents and skills

Skills let a team share its judgment. A skill packages a workflow (steps, commands, pitfalls, success criteria) so any agent can follow it the way your best engineer would. Claude Code itself is built by agents that write and use skills.

Skills (Superpowers)

Skills/Superpowers Ecosystem

Agents load a skill when its description matches the task
Good skills encode what an expert knows: order of operations, what to check, what goes wrong
Agents can improve their own skills by appending lessons learned
Test skills on subagents before trusting them

Which workflows become skills: anything done weekly by more than one team, and anything where a mistake is expensive (migrations, deploys, incident response).

Skill file structure

Each skill is a directory with a SKILL.md. The frontmatter says when to use the skill. The body says how.

<!-- .claude/skills/database-migration/SKILL.md -->
---
name: database-migration
description: Run schema migrations safely with backup and rollback. Use for any schema change or data migration.
---

# Database Migration

## Prerequisites
- [ ] Database credentials in environment
- [ ] Backup storage configured
- [ ] Migration files generated and reviewed

## Steps

### 1. Pre-migration checks
```bash
npx prisma migrate status
```

### 2. Back up
```bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
pg_dump $DATABASE_URL > backups/pre_migration_$TIMESTAMP.sql
ls -la backups/pre_migration_$TIMESTAMP.sql
```

### 3. Migrate
```bash
npx prisma migrate deploy
npx prisma migrate status
```

### 4. Validate
```bash
bun test:db
```

### 5. Roll back (if needed)
```bash
psql $DATABASE_URL < backups/pre_migration_$TIMESTAMP.sql
```

## Common Pitfalls
- Don't run migrations during peak traffic
- Don't skip the backup for "small" changes
- Test on staging first
- Have the rollback command ready before you start

## Success Criteria
- [ ] Migration status shows applied
- [ ] Application starts cleanly
- [ ] Smoke tests pass
- [ ] No unexpected data changes

## Lessons Learned
- Large table index changes need `CREATE INDEX CONCURRENTLY`
- Check for long-running transactions before schema changes

Skill workflow

Describe the workflow to the agent
Have it draft the SKILL.md
Test with pressure scenarios on a subagent (failing tests, pending migrations, missing env vars)
Iterate until it behaves reliably, then check it in

Example skills library

Skill	Purpose
`deployment`	Deploy to staging and production with checks
`database-migration`	Safe schema changes
`code-review`	The team's review checklist
`incident-response`	On-call runbook
`feature-flag`	Adding and removing flags
`api-endpoint`	New endpoints that match house style
`test-writing`	TDD workflow for new features

Example prompts for skills:

Creating:
"Create a skill for database migrations: backup first, run in a transaction,
test rollback, verify data integrity. Include commands and pitfalls."

Testing:
"Test the deployment skill against: pending migrations, failing tests,
env var changes, rollback after a failed deploy. Report gaps."

Improving:
"After this task, append what you learned to the skill's Lessons Learned."

Using:
"Follow the deployment skill to deploy this branch to staging.
Pause before each destructive step."

Own skills like code: give each skill an owner, review its changes, and keep a changelog. Agents apply a stale skill in every session, so outdated practice spreads fast.

Curate. Every installed skill's description costs context in every session. Install what the team uses. Remove what it doesn't.

Agent memory

Agent Memory Architecture

Agents forget everything when a session ends. Without shared memory, every engineer's agent starts from zero, and the team re-explains the same architecture decisions again and again. Memory turns individual discoveries into team knowledge.

What to store:

Architecture summaries and key decisions (with the reasons)
Conventions that tools can't enforce
Pitfalls and lessons learned
Integration details and environment specifics

What it buys the team:

New engineers and their agents onboard from the same source
Consistent answers across team members
Knowledge survives people changing teams

Where it lives:

CLAUDE.md for rules every session needs
.claude/memory/ (checked in) for decisions and background, loaded on demand
ADRs for decisions that need a record of alternatives
An external store only when files stop scaling

Implementing agent memory

Start with files. They're reviewable, diffable, and every tool can read them. Most teams never need more.

<!-- .claude/memory/ARCHITECTURE.md -->
# Architecture Decisions

## Database
- PostgreSQL 16 with pgvector
- Read replicas in us-east-1 and eu-west-1
- Connection pooling via PgBouncer (max 100 connections)

## API Design
- REST for CRUD, GraphQL for complex queries
- Rate limits: 100 req/min free tier, 1000 paid
- All endpoints require JWT except /health and /docs

## Lessons Learned
- No soft deletes for user data (GDPR erasure gets complicated)
- Redis cluster mode caused failover issues; single node with replicas instead
- GraphQL resolvers use DataLoader to avoid N+1

<!-- .claude/memory/CONVENTIONS.md -->
# Coding Conventions

## Naming
- Files: kebab-case (user-service.ts)
- Components: PascalCase (UserProfile.tsx)

## Patterns We Use
- Repository pattern for data access
- Factories for test fixtures
- Constructor dependency injection

## Anti-Patterns
- God classes (split past ~300 lines)
- Raw SQL in controllers (use the repository layer)

Search memory through a subagent so the main context stays clean:

"Before implementing, have a subagent search .claude/memory/ for past decisions
about authentication. Summarize in 3 bullets."

Graduate to vector search only when you have to: thousands of documents, many projects, or content that files can't organize. Then index memory in the same store you use for RAG, summarize sessions with a fast model like Claude Haiku, and keep a human review step before anything becomes "team memory". Memory that is captured automatically and never reviewed fills up with confident, wrong statements.

Memory prompts:

Loading:
"Read .claude/memory/ARCHITECTURE.md and CONVENTIONS.md. List the constraints
that apply to this task."

Saving:
"We decided on write-through caching for sessions. Add it to ARCHITECTURE.md
under Caching Strategy, with the reason."

Searching:
"Search .claude/memory/ for rate limiting decisions. What did we decide and why?"

Available skills

The Superpowers library covers the core engineering workflow:

Skill	When to use
`superpowers:brainstorming`	Before creative or design work
`superpowers:writing-plans`	Multi-step task specs
`superpowers:test-driven-development`	Before implementation
`superpowers:using-git-worktrees`	Feature isolation
`superpowers:subagent-driven-development`	Independent tasks in a plan
`superpowers:systematic-debugging`	Bugs and test failures
`superpowers:executing-plans`	Plan execution
`superpowers:verification-before-completion`	Before claiming done
`superpowers:finishing-a-development-branch`	Implementation complete
`superpowers:requesting-code-review`	Before merging
`superpowers:receiving-code-review`	Acting on feedback
`superpowers:dispatching-parallel-agents`	2+ independent tasks
`superpowers:writing-skills`	Creating and editing skills

Invoke eagerly. If a skill might apply, load it. Loading one is cheap. Skipping a workflow that encodes hard-won judgment is not.