ax-narrate — Claude Code skill: session story and install
This skill turns an agent’s current-session context into a structured story, including code changes, user corrections, abandoned approaches, and consequential tool errors.
npx skills add Necmttn/ax --skill narrate -a claude-codeWhat ax-narrate 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.
What it helps with
- 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 for the agent
- 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.
How to install ax-narrate
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill narrate -a claude-code2Manually: put the files in place
~/.claude/skills/narrate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/narrate/
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill narrate -a codex2Manually: put the files in place
.agents/skills/narrate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill narrate -a cursor2Manually: put the files in place
.cursor/skills/narrate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Necmttn/ax narrate2Manually: put the files in place
.github/skills/narrate/SKILL.md1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill narrate -a gemini-cli2Platform CLI
gemini skills install https://github.com/Necmttn/ax --path skills/narrateManually: put the files in place
.devin/skills/narrate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Necmttn/ax --skill narrate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ax-narrate
How do I install ax-narrate in Claude Code?
Run npx skills add Necmttn/ax --skill narrate -a claude-code. The skill file is available at ~/.claude/skills/narrate/SKILL.md.
What does ax-narrate do?
It writes a JSON account of the current session for ax studio, including changes and important events that a pull request would leave out.
How does ax-narrate identify session turns?
It can retrieve the session ID and turn numbers with the ax sessions commands. When ax is unavailable, it creates an ID itself and uses approximate turn numbers.
