ai-engineering-kit

An opinionated, agent-agnostic AI-development kit — disciplined skills plus a structured workspace — installed and updated through one npx command.

What it is

ai-engineering-kit scaffolds a repeatable workflow for building software with AI coding agents:

• Skills — Markdown playbooks, grouped into categories you pick at install time:
  • core-workflow — discovery → foundations → PRD → plan → implement → review → verify.
  • engineering, productivity, misc — additional day-to-day skills forked from mattpocock/skills (see attribution below).
• A structured workspace — in local mode, ai/ holds ephemeral artifacts (PRDs, plans, reviews); in GitHub modes those become issues/PRs instead. docs/ always holds durable knowledge: foundations/ (vision, guidelines, decisions) plus system/, references/, operations/, and debt/.
• Agent-agnostic wiring — skills live as portable Markdown in ai/skills/; the kit generates the entry file each agent reads (CLAUDE.md + a .claude/skills/ symlink for Claude Code, AGENTS.md for Codex). More agents are a template + a manifest entry away.

Quickstart

npx ai-engineering-kit

Run with no arguments for an interactive install: pick which components (skills / docs / workspace / entry-files), which skill categories, which agents to wire up, and — when you scaffold entry files — which workflow mode to use. The kit previews exactly what it will write, then scaffolds your selection and records it in a .ai-kit.json manifest.

Workflow mode

When agent entry files are part of the install, the kit asks how you want to work with AI and renders one global rule into CLAUDE.md / AGENTS.md that governs every skill at once:

• local — artifacts stay as markdown under ai/ (PRDs, plans, reviews…), as each skill describes.
• github — skills create GitHub issues/PRs via gh instead of saving local files.
• github-loop — everything github does, plus a github-loop skill so a local Claude Code session can drive work from GitHub issues by stage label (no API key, no CI). Launch it with /loop 2m ai/skills/github-loop/SKILL.md.

The choice is saved in .ai-kit.json. Interactive installs always ask; on re-runs the kit re-asks and pre-selects your recorded mode (projects installed before this feature default to local).

Non-interactive

Pass --workflow github|local|github-loop. It is required whenever entry files are selected (including init --all):

# scaffold a chosen set without prompts
npx ai-engineering-kit init --name "My App" \
  --components skills,docs-foundations,entry-files \
  --categories core-workflow \
  --agents claude-code,codex \
  --workflow local

# or everything
npx ai-engineering-kit init --all --name "My App" --workflow github

# preview a plan without writing anything
npx ai-engineering-kit --dry-run --all

Updating & adding parts

Re-run the command in a project that already has the kit and it becomes state-aware (it reads .ai-kit.json):

npx ai-engineering-kit          # interactive: Add parts / Update to latest / both
npx ai-engineering-kit update   # refresh installed parts to the latest version
npx ai-engineering-kit update --workflow github   # also switch the workflow mode
npx ai-engineering-kit add --components ai-workspace   # add a part later

Updates are conflict-aware: files you never touched refresh silently, and any file you edited is surfaced as a conflict with a per-file choice — overwrite with the new version, keep mine, or keep mine and save theirs as <file>.new. Files you added yourself are always preserved. The non-interactive update keeps your edits by default.

Reproducibility

The template content is bundled inside the package and versioned with it, so a pinned version always produces the same scaffold:

npx [email protected] init --all

Credits & attribution

ai-engineering-kit is inspired by and forks skills from Matt Pocock's mattpocock/skills ("Skills For Real Engineers"), distributed under the MIT License. The engineering/, productivity/, and misc/ skill categories are derived from that work. See NOTICE for the retained copyright and license.

Matt's newsletter: https://www.aihero.dev/s/skills-newsletter

License

MIT © Ebert Mota. Forked skills remain © their original authors — see NOTICE.