Alembicalembic

Documentation

Learn how to use Alembic to improve your AI coding assistant experience.

What is Alembic?

Alembic is a library of proven AI "recipes" for coding assistants. Think of it as a community-curated collection of configurations and playbooks that make AI assistants more effective at specific tasks.

AGENTS.md tells an AI assistant the house rules for a project — coding standards, testing requirements, commit conventions, and more.

Skills are step-by-step playbooks for common tasks like code review, refactoring, or writing tests. Each skill includes verification checks and failure mode handling.

Quick Start

Getting started with Alembic takes just a few minutes:

1. Choose an Agent

Browse the Agents page and find one that matches your project type. For example, "Full-Stack Web Development Agent" for React/Node.js projects.

2. Copy to Your Repo

Click the "Copy AGENTS.md" button and paste the file into your repository root:

my-project/
├── AGENTS.md      ← paste here
├── src/
├── package.json
└── ...

3. Customize

Edit the AGENTS.md to match your specific requirements — adjust constraints, add your team's conventions, and customize the testing requirements.

4. Add Skills (Optional)

For specific tasks, copy relevant skills to a /skills folder:

my-project/
├── AGENTS.md
├── skills/
│   ├── code-review/SKILL.md
│   └── testing-strategy/SKILL.md
└── ...

Core Concepts

Quality Tiers

Every entry in the registry has a quality tier:

  • Draft — Experimental, may have rough edges
  • Stable — Reviewed and tested, reliable for most use cases
  • Recommended — Battle-tested, widely adopted, regularly updated

Compatibility

Each entry lists compatible AI assistants. While most recipes work across platforms, some may have features specific to Claude, Copilot, Cursor, or others.

Versioning

We use semantic versioning (X.Y.Z) to track changes:

  • Major (X) — Breaking changes or complete rewrites
  • Minor (Y) — New features or significant improvements
  • Patch (Z) — Bug fixes or minor clarifications

Contributing

Alembic is community-driven. There are several ways to contribute:

Submit a New Entry

  1. Fork the registry repository on GitHub
  2. Create a new folder in agents/ or skills/
  3. Add a meta.yaml and corresponding .md file
  4. Submit a pull request

Improve Existing Entries

Click the "Edit on GitHub" button on any entry page to propose improvements. Small fixes (typos, clarifications) are merged quickly. Larger changes go through review.

Report Issues

Found something outdated or broken? Open an issue with:

  • Which entry is affected
  • What's wrong (outdated, incorrect, missing context)
  • Suggested fix (if you have one)