# kickjs Backend Framework Skill
[](./LICENSE)
A [Claude](https://claude.com/claude-code) skill for working with [KickJS](https://github.com/forinda/kickjs) โ the decorator-driven Node.js framework on Express 5 + TypeScript.
The skill auto-detects which mode applies and loads the matching guidance:
- **Adopter mode** โ when the project depends on `@forinda/kickjs*`. See [`adopter.md`](./skills/kickjs-skill/references/adopter.md) for the full reference.
- **Contributor mode** โ when working in the [`forinda/kickjs`](https://github.com/forinda/kickjs) monorepo itself. See [`contributor.md`](./skills/kickjs-skill/references/contributor.md) for the full reference.
- Both modes share a baseline of invariants documented in [`SKILL.md`](./skills/kickjs-skill/SKILL.md).
## Quick install
```bash
git clone https://github.com/forinda/kickjs-skill ~/dev/kickjs-framework-skill
~/dev/kickjs-framework-skill/scripts/install.sh
```
Symlinks the skill into `~/.claude/skills/kickjs-skill`. Restart your Claude Code session to pick it up.
```bash
~/dev/kickjs-framework-skill/scripts/install.sh --copy # frozen snapshot
~/dev/kickjs-framework-skill/scripts/install.sh --uninstall # remove
CLAUDE_SKILLS_DIR=/some/path scripts/install.sh # custom destination
```
## What it does
When Claude detects you're in a KickJS context (a `kick.config.ts`, an `@forinda/kickjs*` import, a `*.module.ts` file, a mention of "KickJS", or you're inside the kickjs monorepo) it loads the skill and applies the framework's conventions.
A few examples of what changes:
- **Asks for "a new module"** โ scaffolds it via `kick g module <name>` and confirms `*.module.ts` naming, the typed `defineModule({ controllers, routes })` shape, and registration in `src/modules/index.ts`. Avoids the silent-breakage trap of naming the entry `index.ts` (full-restart on every save instead of HMR).
- **Asks for "a new adapter"** โ writes a `defineAdapter()` factory with the right hooks for the job (`beforeMount` for routes that bypass the middleware stack, `middleware()` with explicit `phase`, `shutdown()` for resource cleanup). Won't write a `class implements AppAdapter` โ that pattern was dropped in v4.
- **Asks for "a tenant resolver"** โ writes a `defineHttpContextDecorator({ key: 'tenant', deps, resolve })` instead of `@Middleware()`. Adds the `ContextMeta` augmentation. Reads via `getRequestValue('tenant')` from services. Never reaches for the internal `requestStore.getStore()` API.
- **Asks for "a cron job"** โ directs at the [BYO cron recipe](https://forinda.github.io/kickjs/guide/cron) instead of `pnpm add @forinda/kickjs-cron` (the wrapper was dropped in v5).
- **Asks for "tests for this service"** โ uses `Container.create()` per test, never `Container.getInstance().reset()`. Suggests the in-memory repository pattern when relevant.
- **Asks for "shutdown logic"** โ wires the `shutdown()` hook on the right adapter, mentions `bootstrap({ processHooks })` if a third-party SDK (OTel / Sentry) needs to own the signal handler.
The skill ships ~50 categorised links into the canonical [KickJS docs](https://forinda.github.io/kickjs/guide/) โ when you ask about a specific topic, Claude will reach for the right guide rather than improvising.
## Layout
```
kickjs-framework-skill/
โโโ .claude-plugin/
โ โโโ plugin.json Plugin manifest for marketplace install
โโโ skills/
โ โโโ kickjs-skill/
โ โโโ SKILL.md Always-loaded โ mode detection + invariants
โ โโโ references/
โ โโโ adopter.md Loaded in adopter mode
โ โโโ contributor.md Loaded in contributor mode
โโโ scripts/
โ โโโ install.sh symlink / --copy / --uninstall
โโโ CHANGELOG.md Versioned change log
โโโ README.md This file
โโโ LICENSE MIT
```
Direct links to the skill content:
- [`skills/kickjs-skill/SKILL.md`](./skills/kickjs-skill/SKILL.md) โ mode detection + 8 universal invariants (`defineAdapter` factories, slash-delimited tokens, `Container.create()`, `getRequestValue`, contributors over middleware, BYO recipes, factory-call parens, per-request middleware order, `RequestContext` 3-instance model, DI scope rules, `dependsOn` failing at boot).
- [`skills/kickjs-skill/references/adopter.md`](./skills/kickjs-skill/references/adopter.md) โ project shape, critical wiring rules, decorator surface beyond the basics, adapter lifecycle hooks, plugin contributors, validation behaviour, the two middleware signatures, built-in middleware roster, testing patterns, **53 categorised guide URLs**, and 12 silent-breakage pitfalls.
- [`skills/kickjs-skill/references/contributor.md`](./skills/kickjs-skill/references/contributor.md) โ repo shape, the `packages/core` / `packages/http` deletion rule, build pipeline (Vite + tsc), Vite invariants, lockstep versioning, package add/remove flow, CLI generator extension, BYO doc invariants, doc-ownership map, code style, branching, examples-are-scaffolded rule, lint:tokens, off-roadmap items.
## How it works
Claude loads skills via [progressive disclosure](https://docs.claude.com/en/docs/claude-code/skills):
1. **Frontmatter description (~100 words)** โ always present in Claude's context. Drives whether the skill activates.
2. **`SKILL.md` body (193 lines)** โ loaded as soon as the skill triggers. Covers what every KickJS interaction needs.
3. **Reference files** โ loaded only when needed, based on the mode-detection step in `SKILL.md`. Adopter projects never load contributor guidance and vice versa.
This keeps the always-on cost small. The full skill is 824 lines but Claude only carries ~190 of them by default.
## Compatibility
| KickJS version | Skill version |
| ----------------- | ------------------ |
| v5.x | 0.1.x (current) |
| v4.x | 0.1.x (downgrade docs URLs to /v4/, otherwise compatible) |
| v3.x and earlier | not supported |
Designed for **Claude Code 1.x** with Skills support. Should also work in any Claude runtime that loads `~/.claude/skills/<name>/SKILL.md` โ Codex CLI, Gemini CLI, Copilot CLI all have skill-equivalent mechanisms covered by the [Anthropic skill spec](https://docs.claude.com/en/docs/claude-code/skills).
## Updating
```bash
cd ~/dev/kickjs-framework-skill && git pull
```
If you symlinked (default), the skill is now updated. If you `--copy`'d, also run `scripts/install.sh --copy` again to refresh.
## Versioning
The skill version (in [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json)) is independent of KickJS version. Bumps follow [semver](https://semver.org/):
- **Patch** (`0.1.x`) โ clarifications, new pitfalls, additional guide links.
- **Minor** (`0.x.0`) โ new reference files, restructured guidance, new mode.
- **Major** (`x.0.0`) โ incompatible with the prior KickJS major (e.g. when KickJS v6 ships, the skill v1 cutover happens with it).
See [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
## What the skill does NOT do
- **It doesn't run KickJS commands.** Claude will know when to suggest `kick g module foo`, but the `kick` binary has to come from your project's `@forinda/kickjs-cli` install.
- **It doesn't know your specific project.** Project-local `CLAUDE.md` / `AGENTS.md` always wins when it disagrees with the skill โ the skill says so explicitly and surfaces the disagreement.
- **It doesn't migrate code.** For v3 โ v4 or v4 โ v5 migrations, the skill points at the [migration guide pages](https://forinda.github.io/kickjs/guide/migration-v3-to-v4) but doesn't apply the codemods itself.
- **It's not a marketplace listing.** No telemetry, no auto-update, no remote calls. Just files on disk loaded by Claude.
## Contributing
The skill lives in its own repo (separate from [`forinda/kickjs`](https://github.com/forinda/kickjs)) so the framework monorepo stays focused on the framework. PRs welcome โ particularly:
- **New silent-breakage pitfalls** discovered in real adopter projects.
- **Updates when the framework adds a new decorator / lifecycle hook / convention** โ the skill should learn about it within the same release.
- **Better trigger phrases** in the `description` frontmatter (the field that controls when Claude reaches for the skill).
- **Doc-link maintenance** โ the 53 guide URLs in `adopter.md` should match the current docs site structure.
To verify locally:
```bash
git clone https://github.com/forinda/kickjs-skill && cd kickjs-framework-skill
scripts/install.sh # symlink into ~/.claude/skills/
# Make edits in skills/kickjs-skill/, restart Claude, prompt with a KickJS question.
```
Open a PR with the rule, the source signal that justifies it (production incident / user complaint / framework change link), and ideally a test prompt the skill should now handle correctly.
## License
[MIT](./LICENSE) โ Copyright ยฉ 2026 Felix Orinda.
## Related
- [KickJS framework](https://github.com/forinda/kickjs) โ the framework this skill is paired with.
- [KickJS docs site](https://forinda.github.io/kickjs/) โ adopter-facing guides.
- [KickJS roadmap](https://github.com/forinda/kickjs/blob/main/ROADMAP.md) โ v6+ themed milestones.
- [Claude Code](https://claude.com/claude-code) โ the CLI that loads this skill.
- [Anthropic skill spec](https://docs.claude.com/en/docs/claude-code/skills) โ how progressive-disclosure skills work.