aikit

Personal AI agent conventions, installed from a single source of truth into every tool:

• Claude Code - CLAUDE.md imports .agents/aikit/*.md
• Codex - AGENTS.md carries the same guidelines inlined between managed markers
• Cursor - reads AGENTS.md natively, nothing extra to install
• Grok CLI - reads AGENTS.md, the .mcp.json bridges, and .claude/skills copies natively, nothing extra to install (its personal override lives in ~/.grok/, since Grok skips gitignored files like CLAUDE.local.md)

Each harness loads exactly one copy of the rules; nothing is cross-referenced between tools and nothing loads twice.

Day to day

Set up a new repo:

npx @alfonsobries/aikit@latest init

Detects the stack across the whole monorepo, installs the baseline, scaffolds .agents/index.md, .agents/commands.md and .agents/conventions.md with fill-in placeholders, wires CLAUDE.md/AGENTS.md, and installs the global skills. Fill the placeholders and commit everything.

Add a rule - tell the agent, don't hunt for the file:

/teach never use semicolons          → configures .prettierrc, not prose
/teach we're on Laravel 13 now       → .agents/stack.md (or skips it if Boost reports it)
/teach always confirm before migrations   → .agents/conventions.md (always-on)
/teach before writing tests read X   → .agents/guides/ + pointer in index.md
/teach for all my projects: <rule>   → opens a draft PR against this repo's guidelines/

The skill routes each rule to the one place it belongs, runs aikit update + check, and tells you where it landed. The last form is how a global rule is born: teach edits guidelines/*.md here, opens the PR, and after the next release every repo picks it up via aikit update.

Reorganize a messy repo:

/teach audit

Inventories every rule source (CLAUDE.md, AGENTS.md, .agents/, .claude/, .cursor/), classifies each rule through the same tree, shows a plan table, and applies it after you confirm.

Think out loud without triggering work:

/ja wouldn't it be better to cache this?
/ja no sería mejor mover esto al servidor?

Answers the question, argues its side, and stops. Nothing is edited, run or committed until you say to act, and work already in flight stays where it is. Useful mid-task, where a passing "wouldn't it be better to..." otherwise turns into a refactor nobody asked for.

Low-consumption mode on a strong model:

/eco set the catalog and the media prompts, leave the rest
/manual tu decides el look, otro agente implementa

Keeps this session on judgment (copy, IA, design, the prompt/style contract) and writes docs/ECO.md for a cheaper agent to execute. No tests, CI, web tours, asset generation or trial-and-error here. Not /yolo (do it all) and not /ja (no artifact).

Chase something slow:

/audit-performance the confirmed list takes forever to open
/audit-performance obsessive: this endpoint, squeeze it to the floor

Reproduces the symptom at real scale, baselines it, freezes the current behaviour in tests, changes one mechanism at a time and re-measures after each. It ends by a stated criterion rather than by fatigue: Pareto by default (take the dominant mechanism and stop), obsessive when asked (iterate until the number stops moving). Every pass reports a before and after number.

Set up a new machine:

npx @alfonsobries/aikit@latest skill    # bundled skills for Claude, Codex and Grok

Then in any repo that declares team skills: npx @alfonsobries/aikit skills.

Install

npx @alfonsobries/aikit@latest install

Detects the repo's stacks from every workspace manifest (PHP, Laravel, Pest, JS, React, Vue, Expo) and:

1. Writes the matching guidelines into .agents/aikit/
2. Adds the missing @.agents/aikit/*.md imports at the top of CLAUDE.md
3. Creates or syncs the managed blocks at the top of AGENTS.md
4. Gitignores the personal override files (CLAUDE.local.md, AGENTS.override.md)
5. Registers aikit as a devDependency with a postinstall: aikit update hook (repos with a package.json), so every dev gets the pinned CLI and a fresh sync from a plain pnpm install

Everything below the imports / managed blocks belongs to the repo and is never touched. The always-on blocks are size-budgeted: commands fail before writing when they exceed 28 KiB, and warn when other content pushes AGENTS.md past what Codex reads (32 KiB).

Keep in sync (the doctor)

npx @alfonsobries/aikit@latest update   # rewrite everything managed, fix the gaps below
npx @alfonsobries/aikit@latest check    # CI drift gate, exits 1 when out of sync

There is no separate doctor command - update fixes and check flags, automatically, the monorepo gaps no harness handles on its own:

• Nested MCP servers (e.g. Laravel Boost under api/): root bridges are added to .mcp.json, .cursor/mcp.json and .codex/config.toml so root sessions reach them. Existing entries are never touched.
• Tool-neutral skills in .agents/skills/: each gets a managed copy under .claude/skills/ (Claude Code doesn't read .agents/skills; the other tools do).
• Bundled global skills: installed/refreshed in ~/.claude, ~/.codex and ~/.grok, with any scripts and references they bundle.

Commit every generated artifact - agents and CI working from a clone don't run install hooks. Freshness comes from wiring the updaters where each tool lives:

// composer.json (wherever Laravel lives)
"post-update-cmd": ["@php artisan boost:update --ansi", "npx @alfonsobries/aikit update --path .."]
// package.json (repo root) - install wires this automatically
"postinstall": "aikit update"

and gating drift in CI: aikit check at the root, plus php artisan boost:update && git diff --exit-code in the Laravel directory.

Bundled skills

Shipped with the package and installed globally by npx @alfonsobries/aikit skill, one copy per harness (~/.claude/skills, ~/.codex/skills, ~/.grok/skills), refreshed on every update:

• teach - route a rule to the one place it belongs, or audit the rules a repo already has.
• aim-high - hold the work to what a team that stakes its reputation would ship, and keep the bar from dropping silently.
• create-skill - write, audit and fix SKILL.md skills that run on Claude Code, Codex, Cursor and Grok, with a validator to check one before shipping it.
• ja - "just asking": hold a question as a question, answer it, and change nothing until told to act.
• eco - low-consumption mode: spend this model on high-judgment work and write docs/ECO.md for a cheaper agent. No tests, CI, browsing or asset generation here. /manual is the same.
• audit-performance - run the loop that makes software measurably faster: baseline, freeze the current behaviour in tests, change one mechanism, measure again, and end it by a stated criterion (Pareto or obsessive) instead of by fatigue.
• yolo - drive a self-contained task autonomously: decide instead of asking, commit as you go, open a PR and take its CI to green.
• yolo-gated - the same, with a stop before every commit: build a chunk, show it, commit only on approval.
• audit-agentic - audit a public site against Ora / Is Agentic: scan, close the FAILs that apply, keep machine files current (npx is-agentic <domain>).
• image-gen - generate or edit AI images from any directory (OpenAI gpt-image-2.5 Flare/Sunburst, xAI Grok Imagine 2.0). Needs ~/.config/aikit/image-gen.env.
• audio-gen - text to speech, sound effects, music and multi-speaker dialogue (ElevenLabs, OpenAI, xAI). Needs ~/.config/aikit/audio-gen.env, and reads a personal voice catalog from ~/.config/aikit/audio-gen/voices.tsv.
• sentry-slow-sql - rank SQL from Sentry Insights by time spent (default 7d, --period= to change) and file one GitHub issue per query with the SQL and Sentry metrics only. Does not diagnose or fix. Needs ~/.config/aikit/sentry-slow-sql.env. Token: https://sentry.io/settings/account/api/auth-tokens/new-token/ with org:read, project:read, event:read (not org:ci).

Team skills

Two kinds, two homes:

• Project skills ship in the repo: put them in .agents/skills/ and commit - every clone has them, no install step.
• Global skills (shared across projects, one copy per machine) are declared in the repo's .agents/recommended.yaml:

skills:
  - name: vercel-react-best-practices
    description: 70 React/Next performance rules from Vercel
    install: npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -y
    detect:
      paths:
        - ~/.claude/skills/vercel-react-best-practices
    stacks: [react]

Missing ones surface with a banner on every update and recommend run until the dev runs:

npx @alfonsobries/aikit skills   # runs the declared installs for whatever is missing

Deliberately human-invoked - repo-committed YAML never executes on its own. For the SessionStart nudge: aikit recommend --if-due --hook (skills always; anything else, weekly). Mute with AIKIT_QUIET=1.

Overrides

• Personal (gitignored): CLAUDE.local.md for Claude Code; AGENTS.override.md for Codex; ~/.grok/ for Grok. Cursor personal rules live in its User Rules setting.
• Per-repo: rules below the imports in CLAUDE.md and below the managed blocks in AGENTS.md - or better, in the .agents/ always-on files.
• Permanent: /teach for all my projects: <rule>, review the PR it opens here, merge and release.

Release

npm version minor --no-git-tag-version
pnpm build && node dist/cli.js install
git add -A && git commit -m "$(node -p "require('./package.json').version")"
git tag "v$(node -p "require('./package.json').version")"
git push --follow-tags

The rebuild-and-install step resyncs .agents/aikit/*.md and AGENTS.md's version stamp to the new release - skip it and CI's self-check fails on the tagged commit.

The Publish workflow runs the gate and releases to npm on the version tag (requires the NPM_TOKEN secret).