# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

A collection of markdown guides for developers using AI coding assistants. The guides are consumed by other projects (pasted into chat, added to CLAUDE.md, `.cursorrules`, etc.)  -  this repo itself is not a web app or library.

The only runnable code is the CLI in `bin/init.js`, which users run via `npx ai-instruct init` in their own projects.

## CLI

**Run locally:**
```sh
node bin/init.js                  # standard flow (detect tool, write to ai-docs/)
node bin/init.js --skills         # install as Claude Code skills in .claude/skills/
node bin/init.js --skills --user  # install in ~/.claude/skills/ (user scope)
```

**Test the published package:**
```sh
npx ai-instruct init
```

The CLI has no dependencies  -  it uses only Node.js built-ins (`fs`, `os`, `path`, `readline`) plus the global `fetch` (Node 18+). Do not add external packages.

`bin/lib/guides.js` is the single source of truth for the guide list (filenames, descriptions, skill names, skill descriptions). Both the CLI and the build script import from it.

## Plugin and skills (Claude Code)

The repo also publishes itself as a Claude Code plugin. The plugin bundles all 5 guides as skills under `skills/<skill-name>/SKILL.md`.

- `skills/` is **generated** by `scripts/build-skills.js` from the canonical `*-guide.md` files plus the metadata in `bin/lib/guides.js`. Do not edit `skills/<name>/SKILL.md` by hand  -  edit the source guide and rebuild.
- `skills/` is committed to the repo (not gitignored) so users installing via `/plugin install` get the files without running a build.
- `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` describe the plugin and the marketplace (this repo is its own marketplace, so users can `/plugin marketplace add ziniman/ai-instruct`).
- Versions in those two JSON files are synced from `package.json` by `scripts/sync-versions.js`, which runs automatically as part of `npm version`.

## Release process

The `npm version` and `npm publish` lifecycle hooks handle build and version sync automatically. The full release flow:

1. **Edit content** - update one or more `*-guide.md` files (or add a new guide, see below).
2. **Run the build to verify locally:**
   ```sh
   npm run build:skills          # regenerates skills/<name>/SKILL.md
   ```
   Inspect the diff in `skills/` to make sure the changes look right.
3. **Bump version and sync everything:**
   ```sh
   npm version patch             # or minor / major
   ```
   The `version` lifecycle hook runs `sync-versions.js` (writes new version to `.claude-plugin/plugin.json` and `marketplace.json`) and `build-skills.js`, then `git add`s the updated files. `npm version` itself creates the version bump commit and a git tag.
4. **Push to GitHub:**
   ```sh
   git push && git push --tags
   ```
   This is what `/plugin marketplace add ziniman/ai-instruct` reads from.
5. **Publish to npm:**
   ```sh
   npm publish
   ```
   The `prepublishOnly` hook runs `build-skills.js` again as a safety net.

**Never commit a version bump without running `npm version`** - hand-editing `package.json` skips the sync hook and leaves the plugin/marketplace JSON files out of date.

If you only edit a guide and want to ship a patch without bumping the version (e.g. typo fix on already-released content), just commit the source edit and the regenerated `skills/<name>/SKILL.md` together.

## Guide format (enforced by CONTRIBUTING.md)

Every guide must follow this structure in order:

1. **H1 title** + metadata blockquote (`> Applies to: ... | Updated: Month YYYY`)
2. **Section 0: Before You Start**  -  4 - 6 plain-English questions with defaults, followed by a `> **AI assistant:**` instruction line
3. **Table of contents** (for guides longer than ~150 lines)
4. **Content sections**  -  one concept per section, self-contained

The Section 0 pattern is the core of the approach: questions replace generic boilerplate. Defaults must be detectable from the project (e.g. framework in `package.json`) or a best-practice baseline.

## Adding a new guide

1. Create `kebab-case-name.md` at the repo root
2. Follow the guide format above (read CONTRIBUTING.md for the full spec)
3. Add a row to the `## Guides` table in `README.md` (Guide name | filename link | description)
4. Add the guide to the `GUIDES` array in `bin/lib/guides.js` with `name`, `file`, `desc`, `topic`, `skillName`, and `skillDescription` fields. The `skillDescription` is what triggers the skill in Claude Code  -  write it in the "Use this skill whenever..." style with explicit trigger contexts and skip-for cases (see existing entries).
5. Run `npm run build:skills` to generate `skills/<skillName>/SKILL.md` and commit it alongside the guide
6. Add the guide's raw GitHub URL to `llms.txt`

## Commit style

- No `Co-Authored-By` lines
- Commit message body explains *why*, not just what changed