Torii AI Toolkit

@toriistudio/ai-toolkit is a CLI that installs Torii's AI coding packages into any project. Pick the packages you need, point it at your AI IDE, and the right files land in the right place.

Supported IDEs: Cursor, Claude Code, Codex, and a generic custom folder layout.

Landing page: https://toriistudio.github.io/ai-toolkit (coming soon)

Using the toolkit

Quickstart

npx @toriistudio/ai-toolkit@latest

The CLI asks which IDE you're using, which packages you want, and runs any package-specific prompts (e.g. UI framework for the guardrails package). All prompts can also be skipped via flags — see below.

Available packages

| Package | What it installs | |---|---| | guardrails | Rule + agent-skill packs for naming, structure, DRY, imports, code quality. Picks Tailwind / Material UI / no-framework add-ons based on a prompt. | | perf-improve | Lighthouse-driven loop for diagnosing and fixing React app performance regressions. Details. |

Packages are auto-discovered from src/packages/*/manifest.json — adding a new one does not require a code change to the CLI.

CLI flags

| Flag | Values | Description | |---|---|---| | --platform, -p | cursor, claude, codex, custom | Target IDE. | | --install-dir, --dir | path | Install root (mainly for --platform custom). | | --with | comma-separated package ids, or all | Non-interactive package selection. | | --force | flag | Overwrite seed files (PATTERNS.md, LOGS.md, .gitignore) on re-install. |

Examples:

# Interactive
npx @toriistudio/ai-toolkit@latest

# Targeted
npx @toriistudio/ai-toolkit@latest --platform cursor --with guardrails
npx @toriistudio/ai-toolkit@latest -p claude --with perf-improve
npx @toriistudio/ai-toolkit@latest -p custom --dir ./ai-config --with all

# Re-install and overwrite user-edited seed files
npx @toriistudio/ai-toolkit@latest -p claude --with perf-improve --force

Where files land

| IDE | Rules | Agent skills | |---|---|---| | Cursor | .cursor/rules/<id>.mdc | .cursor/skills/<id>/SKILL.md | | Claude Code | .claude/rules/<id>.md | .claude/skills/<id>/SKILL.md | | Codex | Merged Torii block in AGENTS.md | .agents/skills/<id>/SKILL.md | | Custom | <install-dir>/rules/<id>.md | <install-dir>/skills/<id>/SKILL.md |

Contributing a package

Packages live under src/packages/<id>/. Each package folder contains a manifest.json plus the content the manifest references. The CLI auto-discovers packages from this folder.

Manifest shape (manifest.json)

{
  "id": "<must match folder name>",
  "label": "Short label shown in the CLI multi-select",
  "description": "One-line summary of what this package installs.",
  "prompts": [
    {
      "id": "framework",
      "type": "select",
      "message": "Which UI stack?",
      "choices": [
        { "value": "tailwind", "label": "Tailwind / shadcn" },
        { "value": "other", "label": "Other / none" }
      ]
    }
  ],
  "outputs": [
    { "type": "tree", "source": "." },
    { "type": "bundle", "source": "bundles/base" },
    { "type": "bundle", "source": "bundles/tailwind", "when": "framework=tailwind" }
  ]
}

• prompts — optional. Each prompt's answer is available to when predicates as <promptId>=<value>. Currently only select prompts are supported.
• outputs — required, non-empty.
  • type: "tree" — copy every file under source verbatim into <ide-skills-dir>/<package-id>/. skill.md is renamed to SKILL.md. manifest.json is excluded.
  • type: "bundle" — each immediate subdir of source is treated as a rule.md + skill.md pair, namespaced by the subdir name (becomes its own IDE skill folder).
• when — optional, format "<promptId>=<value>". Omit for "always install."

Authoring steps

1. Copy src/packages/_template/ to src/packages/<your-package-id>/.
2. Edit manifest.json — make sure id matches the folder name and the file list under outputs references real files.
3. Add your content. For tree packages, files like PATTERNS.md, LOGS.md, and .gitignore are treated as user seeds — preserved on re-install unless --force is passed.
4. Run npm test and npm run build.
5. Smoke test with the local CLI:

   npm link
   # in a scratch project
   ai-toolkit-init --platform custom --dir ./out --with <your-package-id>

6. Open a PR. The PR template will prompt you for what to confirm.

Authoring a rule + agent-skill bundle

When a package emits one or more rule.md/skill.md pairs (the bundle output type), each pair lives in its own subdirectory:

src/packages/<your-package-id>/
  manifest.json
  bundles/
    base/
      <bundle-id-a>/
        rule.md
        skill.md
      <bundle-id-b>/
        rule.md
        skill.md

rule.md is the IDE-rule content. skill.md is the Claude/Cursor agent-skill content. Frontmatter name: should match the bundle folder name. See src/packages/guardrails/bundles/base/* for real examples.

Local development

Requirements

• Node.js (CI runs on Node 22)
• npm

Setup

npm ci

Common scripts

npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # produces dist/, copies src/packages → dist/packages
npm start         # node dist/cli.js

Testing the published-style CLI locally

# in this repo
npm run build && npm link

# in a separate test project
ai-toolkit-init --platform cursor --with guardrails

# cleanup
npm unlink   # (and `npm unlink @toriistudio/ai-toolkit` in the test project)

Release process

Releases are automated by semantic-release on pushes to main:

1. CI runs npm ci && npm test && npm run build.
2. npx semantic-release analyzes Conventional Commits, bumps the version, publishes to npm, cuts a GitHub release, updates CHANGELOG.md, and commits the release artifacts.

Commit conventions (from .releaserc.json):

• feat: → minor
• fix:, perf:, revert:, chore: → patch
• feat!: or BREAKING CHANGE: footer → major
• chore(release): → no release

License

MIT © Torii Studio