# ax-narrate

This skill turns an agent’s current-session context into a structured story, including code changes, user corrections, abandoned approaches, and consequential tool errors.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 121
- Author: Necmttn
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Necmttn/ax/tree/HEAD/skills/narrate/SKILL.md
- Updated: 2026-10-07
- HTML: https://affpapa.org/en/nevibecode/skills/ax-narrate

## What it does

ax-narrate writes a JSON artifact for viewing in ax studio. It arranges the work into narrative stops, each backed by evidence such as code fragments, conversation turns, or failures. This preserves events that would not appear in a pull request.

The skill looks up the session ID with `ax sessions here --days=1 --json` and can retrieve actual turn numbers using `ax sessions show <id> --json`. If `ax` cannot be used, it builds an ID from the repository name and time; turn numbers are then approximate. That fallback means links to conversation turns may be less precise.

The result goes to `.ax/narrations/<session-id>.json` and follows the `SessionNarration` schema. Each stop needs supporting evidence, and user corrections and consequential tool failures need their own anchors. Install with `npx skills add Necmttn/ax --skill narrate -a claude-code`; the skill file is at `~/.claude/skills/narrate/SKILL.md`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Necmttn/ax --skill narrate -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/narrate/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/narrate/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Necmttn/ax --skill narrate -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/narrate/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Necmttn/ax --skill narrate -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/narrate/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Necmttn/ax narrate
```

2. **Manually: put the files in place**
- File: `.github/skills/narrate/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Necmttn/ax --skill narrate -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Necmttn/ax --path skills/narrate
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/narrate/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Necmttn/ax --skill narrate -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Necmttn/ax/tree/HEAD/skills/narrate/SKILL.md

## When to use it
- turn an agent session into a story for ax studio
- record user corrections and abandoned approaches
- tie session events to code fragments and conversation turns
- write a session artifact that follows the narration schema

## Example prompts
- Write a structured account of what happened in this session.
- Capture the changes we made, including my corrections and failed attempts.
- Prepare this session’s story for ax studio.

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

From the same set: [necmttn/ax](https://affpapa.org/en/nevibecode/by/necmttn/ax.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md