Docs

Create a kit

A kit is a folder with a kit.json and, optionally, files that get copied into the project. The fastest way is to generate it from a project you already like.

Don't use the terminal? Let your agent do it

Copy a prompt and paste it into your agent: it runs the commands and explains each step.

  1. 1Open your agent in a folder
  2. 2Paste the prompt
  3. 3Answer its questions
claude-codecursorgemini-cligithub-copilotand any agent with a terminal

Turns your project into a kit so your next ones start the same way and, if you like, publishes it.

I want to turn this project into a first-commit kit so I can start my next projects the same way. I'm not technical: explain in plain words what you'll do at each step and ask me before installing anything. 1. Install the first-commit skill: npx skills@latest add Marlon-Chaviano/first-commit --skill first-commit 2. Create the kit from this folder, answering whatever you can work out yourself; only ask me for the name and description: npx create-first-commit create 3. Explain what the kit includes (dependencies, skills, options) and, if you think something should be removed or added, suggest it. 4. Check that it works: npx create-first-commit test ./kit 5. If I want to share it, help me publish it with npx create-first-commit login and npx create-first-commit publish ./kit.

1. From your project

Inside a Next.js, Expo, Hono, WXT or Vite project:

$ npx create-first-commit create

It detects the following and lets you review it before writing anything:

  • The framework, and with it the official command that creates the base project.
  • The libraries from the catalog you use (shadcn, Kokonut UI, Motion, Sentry…), which become options with their rule in AGENTS.md.
  • Your own dependencies, minus the ones the base template already brings.
  • Your skills (from skills-lock.json), MCP servers (.mcp.json) and variables (.env.example; it never reads .env).
  • Your AGENTS.md instructions, minus what first-commit or the scaffolder generate.
  • Your own files you choose to copy (config, utilities). None by default.

The kit ends up in ./kit. Without questions: npx create-first-commit create -y --name my-kit --include src/lib. If the framework isn't recognized, pass the base command with --base "…".

2. By hand

$ npx create-first-commit create --blank my-kit

Creates a minimal kit.json with the schema linked, so your editor autocompletes it. Every field is in the reference.

3. Variants with extends

A kit can start from another one and declare only what changes. Lists (dependencies, skills, tasks) are added up, objects (env, mcp, libraries) are merged, instructions are appended, and an option with the same id is merged field by field with the parent's (so you can change just its default).

{
  "name": "landing-dark",
  "version": "0.1.0",
  "extends": "landing-next",
  "title": "Dark landing page",
  "libraries": { "addons": ["magicui"] },
  "instructions": "## Style\n\nEverything in dark mode."
}

The parent can be an official kit, a repo (user/repo/kit) or a local path, with an optional version (landing-next@1.0.0). Up to 3 levels are allowed.

4. Try it

$ npx create-first-commit ./kit my-project --dry-run

Shows every command and file without running anything. Drop --dry-run to create the project for real, and build it before sharing it.

5. Publish and version it

Push the kit to a public GitHub repo and publish it from the terminal (with a token from your account) or from the website:

$ npx create-first-commit login
$ npx create-first-commit publish ./kit

It appears in the catalog as your-user/kit-name, pinned to the published commit and with its integrity hash. Without publishing, it can also be installed straight from GitHub:

$ npx create-first-commit your-user/your-repo/kit

Every change bumps version (semver) in kit.json and creates a git tag with that number. That way a specific version can be installed: npx create-first-commit your-user/your-repo/kit@v1.2.0. To appear in the official catalog, open a PR that adds your kit to registry/kits/.

6. Verify it

npx create-first-commit test ./kit installs the kit with several combinations of options in temporary folders, runs its check (verify.command, build by default) and writes a report. For the Verified badge, run it in GitHub Actions: the report is signed with the repository's OIDC token, so nobody can fake it.

# .github/workflows/kit.yml
name: Verify kit
on: { push: { branches: [main] } }
permissions: { contents: read, id-token: write }
jobs:
  verify:
    strategy: { matrix: { os: [ubuntu-latest, macos-latest] } }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: Marlon-Chaviano/first-commit/actions/verify@main
        with: { kit: ./kit }

To choose which combinations to test, define verify.matrix in kit.json (see the reference). Unverified community kits show a warning before running and, with -y, require --allow-commands.

Best practices

  • Write instructions as concrete rules ("add dependencies with npx expo install"), not as descriptions.
  • Use catalog libraries instead of loose dependencies: they bring their skill, their config and their rule.
  • What can't be automated (creating an account, pasting a key) goes in setupTasks, not in the instructions.
  • Prefer official skills from each tool's own organization.
  • Don't copy your whole app: a kit is a starting point, not a clone.

Security

A kit runs commands on the machine of whoever installs it. The CLI always shows the full plan and, unless you pass -y, asks for confirmation. Review third-party kits as you would review a script.