CLAUDE.md ยท diff
git:20260225.832502c to git:20260420.0a6f905
47 added, 5 removed. Audit A to A.
# 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
+ 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`, `path`, `readline`) plus the global `fetch` (Node 18+). Do not add external packages.
+ 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.
- To publish a new version to npm: bump `version` in `package.json`, then `npm publish`.
+ `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/init.js` with `name`, `file`, `desc`, and `topic` fields
- 5. Add the guide's raw GitHub URL to `llms.txt`
+ 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