ax-add-ingest-stage — Claude Code skill: what it does, how to install
Guides the addition of SurrealDB tables and pipeline ingest stages in the ax repository. Keeps changes aligned with strict CI verification gates.
npx skills add Necmttn/ax --skill ax-add-ingest-stage -a claude-codeWhat ax-add-ingest-stage does
This skill enforces project-specific conventions when updating the ax graph codebase. When you declare a SurrealDB table, the skill guides adding DEFINE TABLE ... SCHEMAFULL into packages/schema/src/schema.surql, serializing nested payloads to JSON strings, and updating SCHEMA_TABLES. A missed registration breaks CI immediately. Running bun install inside your worktree is mandatory so schema packages resolve locally instead of pointing to main-tree symlinks.
For ingest steps, the skill outlines co-locating StageDef with stage code and appending keys to apps/axctl/src/ingest/stage/registry.ts. You also need to increment stage counts in effect-cli.test.ts and sort entries under --derive-only. Stage execution must sit inside Effect.catchCause to prevent individual errors from aborting the pipeline. It also covers Effect v4 beta patterns, such as using Schema.Literals instead of collapsed literals.
What it helps with
- add a new SurrealDB table to the schema without breaking mirror tests
- register ingest stages in the central axctl registry
- update CLI test expectations for the --derive-only option
- keep documentation in sync across llms.txt and cli.md for new subcommands
Example prompts for the agent
- Add a new SurrealDB user_sessions table to packages/schema/src/schema.surql and register it
- Create a new derive-metrics ingest stage in axctl and update the stage registry
- Document the new axctl subcommands so they pass check-cli-reference CI gates
How to install ax-add-ingest-stage
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill ax-add-ingest-stage -a claude-code2Manually: put the files in place
~/.claude/skills/ax-add-ingest-stage/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ax-add-ingest-stage/
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill ax-add-ingest-stage -a codex2Manually: put the files in place
.agents/skills/ax-add-ingest-stage/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill ax-add-ingest-stage -a cursor2Manually: put the files in place
.cursor/skills/ax-add-ingest-stage/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Necmttn/ax ax-add-ingest-stage2Manually: put the files in place
.github/skills/ax-add-ingest-stage/SKILL.md1Skills CLI (Vercel)
npx skills add Necmttn/ax --skill ax-add-ingest-stage -a gemini-cli2Platform CLI
gemini skills install https://github.com/Necmttn/ax --path .ax/skills/ax-add-ingest-stageManually: put the files in place
.devin/skills/ax-add-ingest-stage/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Necmttn/ax --skill ax-add-ingest-stage -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-add-ingest-stage
How do I install ax-add-ingest-stage in Claude Code?
Run npx skills add Necmttn/ax --skill ax-add-ingest-stage -a claude-code in your terminal.
What does ax-add-ingest-stage do?
It guides engineers through registering database tables and ingest stages in the ax codebase. The rules guarantee that required mirror tests and CI checks pass.
Why must ingest stage logic be wrapped in Effect.catchCause?
Wrapping stage execution in Effect.catchCause produces zero-row stats on failure. This prevents an error in an individual stage from halting the broader ingest run.
