kickjs Backend Framework Skill

A Claude skill for working with 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 for the full reference.
• Contributor mode — when working in the forinda/kickjs monorepo itself. See contributor.md for the full reference.
• Both modes share a baseline of invariants documented in SKILL.md.

Quick install

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.

~/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 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 — 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 — 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 — 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 — 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:

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

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.

Updating

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) is independent of KickJS version. Bumps follow semver:

• 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 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 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) 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:

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 — Copyright © 2026 Felix Orinda.

Related

• KickJS framework — the framework this skill is paired with.
• KickJS docs site — adopter-facing guides.
• KickJS roadmap — v6+ themed milestones.
• Claude Code — the CLI that loads this skill.
• Anthropic skill spec — how progressive-disclosure skills work.