# Alembic

> >

- **Type:** Skill
- **Install:** `agentstack add skill-frangsierra-alembic-alembic`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [FrangSierra](https://agentstack.voostack.com/s/frangsierra)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [FrangSierra](https://github.com/FrangSierra)
- **Source:** https://github.com/FrangSierra/Alembic/tree/main/skills/alembic

## Install

```sh
agentstack add skill-frangsierra-alembic-alembic
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Use Alembic when raw shell output is large enough to waste context or hide the real signal.

## When To Use

- Long test runs, CI logs, stack traces, `git diff`, `rg`/`grep` output, watch output
- Questions that only need failures, filenames, risk signals, or a short state summary

## When Not To Use

- Short output already easy to read
- Interactive or TUI commands
- Cases where exact raw formatting is the point

## Helper Resolution

Use this order:

1. If `alembic` is already on `PATH`, use it.
   Prefer `command -v alembic >/dev/null 2>&1` over `which alembic`, because some shells print "not found" text to stdout.
2. Otherwise, look for the first existing helper in these locations and use `node  ...`:
   - `~/.codex/skills/alembic/runtime/bin/alembic.mjs`
   - `~/.claude/skills/alembic/runtime/bin/alembic.mjs`
   - `./tooling/alembic/bin/alembic.mjs`
   - `./alembic/runtime/bin/alembic.mjs`
   - `./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs`
3. When you probe manually in shell, check for existence with `-e`, not executability with `-x`, because the helper is a Node entrypoint and may not have the execute bit set.
4. A safe probe is:

```bash
if command -v alembic >/dev/null 2>&1; then
  echo alembic
elif [ -e "$HOME/.codex/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node $HOME/.codex/skills/alembic/runtime/bin/alembic.mjs"
elif [ -e "$HOME/.claude/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node $HOME/.claude/skills/alembic/runtime/bin/alembic.mjs"
elif [ -e "./tooling/alembic/bin/alembic.mjs" ]; then
  echo "node ./tooling/alembic/bin/alembic.mjs"
elif [ -e "./alembic/runtime/bin/alembic.mjs" ]; then
  echo "node ./alembic/runtime/bin/alembic.mjs"
elif [ -e "./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node ./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs"
else
  echo missing
fi
```
5. If none of those exist, skip Alembic and work from raw output.

## Usage Rules

- Use `--level flame` for normal reduced output, `--level ember` for one-line output, and `--level ash` to suppress success noise while still surfacing failures and prompts.
- Prefer `--preset tests|actions|mcp|docker|k8s|safety|files|summary|logs|approval` when one of the built-in output contracts already matches the task.
- Use `--drop-level TRACE,DEBUG,INFO` to remove noisy tagged log lines before reduction.
- Use `--keep-level ERROR,WARN` when the user wants only tagged high-severity log lines plus their immediate continuation lines.
- If both `--preset` and `--question` are present, `--question` wins.
- Prefer `alembic exec --question "..." -- ` for long-running commands when exit status matters.
- Prefer `alembic benchmark exec --question "..." -- ` when the user wants proof that Alembic is reducing a noisy workflow usefully on the current repo.
- Prefer `alembic benchmark diff --base main --question "..."` when the user wants to compare raw diff context versus Alembic on the current branch.
- Prefer `alembic effort --format json --requested  "..."` at prompt-submit or plan-start hook boundaries when you want a local effort recommendation.
- Prefer `alembic hook-config show --host claude|codex` or `alembic hook-config set --host claude|codex ...` when the user wants Alembic hook defaults persisted.
- Prefer `alembic init` for `AGENTS.md` rules and `alembic init claude` for `CLAUDE.md` rules when the user wants repo-local instructions that tell future agents when to use `$alembic` and when to run the effort heuristic.
- Prefer `alembic benchmark effort --set smoke` when tuning or validating the effort heuristic on the current repo.
- Add `--verbose` to `benchmark` only when the user wants artifact paths, timing, the wrapped command, or a raw preview for debugging.
- Use `command 2>&1 | alembic "..."` only when wrapping an existing one-liner is simpler.
- Ask fully explicit questions. Name the exact output shape you want.
- Answer from Alembic output first. Open `artifactPath` only if the reduced output is still insufficient.
- Alembic summarizes the provided output. It does not verify repo truth on its own.
- Alembic reduces wrappers, not requested facts.
- For MCP transcripts, preserve requested rows, fields, groups, filters, or JSON whenever the captured payload already contains that data.
- Alembic works well with noisy MCP-related output emitted by Claude Code or Codex, including terminal captures and agent-emitted JSONL `mcp_tool_call` events, but it does not launch MCP servers or control the protocol directly.
- If the task changes from summarization to diagnosis or root-cause analysis and a repo is available, reduce the noisy output first, then verify against local files before asserting causes.
- Alembic core is local and deterministic. Do not require network or API keys for the default path.

## Examples

```bash
node /absolute/path/to/alembic-helper exec --level ash --preset tests -- npm test
```

```bash
node /absolute/path/to/alembic-helper benchmark exec --level flame --preset tests -- npm test
```

```bash
gh run view --log | node /absolute/path/to/alembic-helper --level ember --preset actions
```

```bash
cat mcp-trace.log | node /absolute/path/to/alembic-helper --level ember --preset mcp
```

```bash
docker build . 2>&1 | node /absolute/path/to/alembic-helper --level ember --preset docker --drop-level INFO,DEBUG
```

```bash
kubectl describe pod api-123 | node /absolute/path/to/alembic-helper --level ash --preset k8s --keep-level ERROR,WARN
```

```bash
node /absolute/path/to/alembic-helper benchmark diff --level ember --preset safety --base main
```

```bash
node /absolute/path/to/alembic-helper benchmark diff --level flame --preset safety --base main --verbose
```

```bash
node /absolute/path/to/alembic-helper effort --format json --requested high "Render four read-only cards in one desktop shell."
```

```bash
node /absolute/path/to/alembic-helper benchmark effort --set smoke
```

```bash
node /absolute/path/to/alembic-helper init
```

```bash
node /absolute/path/to/alembic-helper init claude
```

```bash
git diff -- src | node /absolute/path/to/alembic-helper --level ember --preset summary
```

```bash
node /absolute/path/to/alembic-helper --level ash --preset approval
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [FrangSierra](https://github.com/FrangSierra)
- **Source:** [FrangSierra/Alembic](https://github.com/FrangSierra/Alembic)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-frangsierra-alembic-alembic
- Seller: https://agentstack.voostack.com/s/frangsierra
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.