BalaKit is a kit of files your coding agent already knows how to load. Standing rules go into AGENTS.md (and the matching files for Claude Code, Cursor, and Codex). Skills are playbooks you call by name, such as /inception or kit-workflows. Take what you like. Ignore the rest.

It is not a personality pack and not a sticky chat mode. Mental continuity lives in a separate CLI.

Quick start

Requires Node.js 18 or newer.

npx balakit@latest init -y

Run that in the project directory, not in $HOME. npx balakit without @latest will use a local node_modules/balakit or a global install if one exists, which can be months old.

That writes standing rules and the default engineering skills into this repository. Reload the agent window. Then ask by skill name: "walk through how auth works" or /inception add a CSV export.

Preview first with --dry-run. Skip the skills and keep only rules with --rules-only. Install the same kit for every project on this machine with --scope user:

npx balakit@latest init --dry-run
npx balakit@latest init --rules-only -y
npx balakit@latest init --scope user -y

User scope also copies Cursor plugins to ~/.cursor/plugins/local/. Check the kit with npx balakit doctor (that is not mental doctor).

No menus: pass -y. Guided setup: npx balakit with no flags.

Try inception

After init, plan without hunting the skills table:

• /inception <request> asks when blocked. In Agent mode it writes .balakit/plans/<slug>.md.
• /inception --circuit <request> skips waits and stops at the plan.
• /inception --autopilot <request> writes the plan, then runs execute (degrades if Plan Mode is on).

Full contract: inception.

What you get

| Layer | What it is | When it runs | | --- | --- | --- | | Standing rules | Always-on behavior: simplicity, testing, comments, changelog, one version when you ship | Every task | | Engineering skills | Playbooks you invoke: how / why / is it safe, plan, audit, compare, prove, ship | When you ask, or when the skill's apply-when matches | | Extra packs | SEO, marketing, media (Fal.ai), NotebookLM, stealth browser | npx balakit add … or a native plugin |

Default init does not install SEO, marketing, media, NotebookLM, or cloakbrowser-fallback. Add those when you need them.

Two scopes: --scope project (this repo, default) vs --scope user (this machine). Details: Install.

Skills

Ask the agent by name. One sentence each. Full pages: Skills.

Understand and change code

| You want | Skill | What it does | | --- | --- | --- | | How does this work? | subsystem-walkthrough | Explains architecture, runtime flow, and ownership | | Why is it shaped this way? | design-rationale | Investigates history. Every claim gets an evidence label | | Is this diff safe? | proving-change-safety | Names one safety fact and proves it by running real code | | Bug, small feature, or refactor | kit-workflows | Matches one playbook. Not a sticky mode | | Nothing else fits | unmatched-workflow | Designs a falsifiable playbook for the leftover work | | Audit what already exists | dissect | Red-teams an existing service, schema, or plan | | Compare approaches before building | deep-deliberation | Checkpointed option comparison | | A durable, file-level plan | inception | Writes the plan and stops. Recommends execute | | Parallel takes, no writes | opinion | Current model by default; auto-pick for other families. This chat does not edit | | Workers research, then do the work | execute | Same fan-out, then this chat implements |

dissect, deep-deliberation, and inception share --circuit (skip waits) and --autopilot (take recommended choices). On inception, circuit still stops at the plan. Only --autopilot runs execute.

Prove behavior

| You want | Skill | What it does | | --- | --- | --- | | Drive the app like a user | generating-app-verify | Writes a repo-local verify skill for the real app | | Keep that map honest | refreshing-app-verify | Re-drives every mapped feature. Does not patch product code |

Author skills and docs

| You want | Skill | What it does | | --- | --- | --- | | Write a Skill or rule | authoring-skills-and-rules | Frontmatter, layout, and craft across agents | | A/B a Skill or prompt change | blinded-eval | Isolated candidates, the same organic prompt, judge from artifacts | | Write a README or guide | documentation-writer | One Diátaxis mode, then STE / Global English | | Cut a GitHub / npm release | release-deploy | Tag-triggered releases from the changelog | | Browser automation is blocked | cloakbrowser-fallback | Stealth Chromium when 403 / Turnstile / CAPTCHA stops you |

cloakbrowser-fallback is opt-in (npx balakit add cloakbrowser-fallback), not part of default init.

Marketing, SEO, media (opt-in)

| You want | Skill | Pack | | --- | --- | --- | | Technical / semantic / AI search SEO | everything-seo | npx balakit add everything-seo | | Audit a public page | seo-audit | npx balakit add seo-audit | | Make a site discoverable to agents | agent-ready | npx balakit add agent-ready | | Copy psychology | marketing-psychology | npx balakit add marketing-psychology | | Startup GTM and distribution | startup-marketing-brain | npx balakit add startup-marketing-brain | | Images and video via Fal.ai | media-gen | npx balakit add media-gen | | NotebookLM CLI and MCP | nlm-skill | npx balakit add nlm-skill |

Or install the matching plugin pack.

Standing rules

Default init installs these five. They are always on.

| Rule | What it does | | --- | --- | | base | Meta-principle, dual-mode chat, simplicity ladder, repo hygiene | | testing | Tests must catch a real bug. Prove behavior on the real artifact | | comments | Document why, not what. Every exported symbol gets a doc comment | | changelog | CHANGELOG.md grouped as Features / Fixes / Changes | | release | Git tag, changelog heading, package.json, and npm publish share one semver |

seo-ai-search is file-scoped SEO + AI-search implementation. Add it when you ship public pages: npx balakit add seo-ai-search.

Commands

npx balakit                         # guided setup
npx balakit@latest init -y          # this repo: rules + engineering skills
npx balakit@latest init --scope user -y
npx balakit init --rules-only -y    # standing rules only
npx balakit add dissect --scope user
npx balakit list
npx balakit status
npx balakit doctor
npx balakit update
npx balakit remove testing

npm install -g balakit
balakit init -y

--agents <ids|all> selects skills.sh targets (default: detect). --personal and --mental-* print a URL and exit. Full flag list: CLI.

Native plugins

This repo is a marketplace, not one plugin. Do not /add-plugin the repo root.

Five Agent Plugins 1.0.0 packs live under plugins/ (balakit-engineering, balakit-marketing, balakit-media, balakit-nlm, balakit-seo-skills). Cursor also has two rules-only plugins (balakit-core, balakit-seo). Plugin install loads skills. It does not write AGENTS.md. You still run balakit init for standing rules.

# Claude Code
/plugin marketplace add afaraha8403/balakit
/plugin install balakit-engineering@balakit

# Codex CLI (ChatGPT uses the Plugins tab; same catalog)
codex plugin marketplace add afaraha8403/balakit
codex plugin add balakit-engineering@balakit

# GitHub Copilot CLI
copilot plugin marketplace add afaraha8403/balakit
copilot plugin install balakit-engineering@balakit

Per-client notes and filesystem destinations: Install.

Paste this into your agent

Install BalaKit from https://github.com/afaraha8403/balakit (npm package: balakit).

Run: npx balakit@latest init --scope <project|user> -y
That writes standing rules (AGENTS.md / CLAUDE.md / .mdc) and default engineering skills.
User scope also copies Cursor plugins to ~/.cursor/plugins/local/.

Optional extras (native plugin when this client can; otherwise skip):
  Cursor: add marketplace https://github.com/afaraha8403/balakit — do not /add-plugin the repo root.
  Claude Code: /plugin marketplace add afaraha8403/balakit then /plugin install <name>@balakit
  ChatGPT / Codex: Plugins tab or `codex plugin …`. OpenAI IDE extension: no plugins.
  Copilot CLI: copilot plugin marketplace add afaraha8403/balakit

Then: npx balakit@latest doctor
Reload Cursor if plugins/local changed. Do not npm publish.

Compatibility

| Client | Skills | Standing rules | | --- | --- | --- | | Cursor | Native Agent Plugins, or user-scope init copies to ~/.cursor/plugins/local/ | init → .mdc + AGENTS.md | | Copilot / VS Code | Point at a plugins/balakit-* folder, not the repo root | init | | Amazon Q / Kiro | Agent Plugins under plugins/balakit-*. skills.sh id is kiro-cli | init → AGENTS.md if it reads it | | ChatGPT / Codex | One OpenAI plugin catalog. ChatGPT: Plugins tab. Codex CLI: codex plugin …. IDE extension: no plugins. | init → ~/.codex/AGENTS.md for Codex CLI | | Claude Code | Marketplace only (.claude-plugin/). Root plugin.json is invisible | init → CLAUDE.md | | OpenCode, Cline, Kilo, Windsurf, Gemini CLI, … | CLI / skills.sh | init → AGENTS.md if they read it |

Aider has no skills.sh id (rules only). Google Jules is listed in the CLI matrix but is never auto-detected.

FAQ

This repo or this machine? This repo → --scope project (default). Every project on this PC → --scope user.

Skills missing after init? Default init installs engineering skills. --rules-only skips them. Marketing / SEO / media / nlm / cloakbrowser-fallback still need add or a plugin. Reload the agent window.

Do native plugins replace the CLI? No. Plugins load skills (and Cursor plugins can load rules). balakit init still writes the standing kit.

More answers: FAQ.

Developing

skills/ and rules/ are the source of truth. Generated plugin trees and marketplace catalogs come from ./sync.sh.

./sync.sh
npm test
npm run lockstep

powershell -ExecutionPolicy Bypass -File .\sync.ps1

Never hand-edit generated plugin version fields. Bump package.json, then ./sync.sh.

CI on master / staging runs tests and lockstep. A v* tag runs .github/workflows/release.yml (GitHub Release + npm publish). Repo secret NPM_TOKEN must be an npm Automation token.

bin/cli.mjs                 # entry
skills/<name>/SKILL.md      # skills source
rules/<name>.mdc            # rules source
plugins/<name>/             # generated domain plugins
docs/                       # install, CLI, skills catalog, FAQ
.cursor-plugin/marketplace.json

Docs

| Page | Mode | | --- | --- | | Skills | What each playbook does | | Install | Scopes, plugins, destinations | | CLI | Commands, flags, agent ids | | FAQ | Troubleshooting | | Mental (moved) | Pointer to the standalone CLI |

npm: balakit · repo: afaraha8403/balakit · license: MIT