ai-instruct: Instructions file for Claude Code

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:

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:

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, section summaries) and for the skill builder that turns a guide into skill files. 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 anything under skills/ by hand - edit the source guide and rebuild.
• The splitting logic (buildSkillFiles) lives in bin/lib/guides.js, shared by the build script and the CLI. Skills use progressive disclosure: if a guide's single-file skill would exceed 500 lines, the build writes skills/<name>/SKILL.md with the frontmatter, the guide header, Section 0 in full, and a linked index, plus one skills/<name>/references/<slug>.md per remaining H2 section. The guide's own "Contents" section is replaced by that index. Intra-guide #anchor links are rewritten to point at the right reference file. Shorter guides stay a single SKILL.md. The guides themselves stay single files because they are also used outside Claude Code.
• Each index entry needs a one-line "when to read this" summary: the section's Applies when: line, or an entry in that guide's sectionSummaries map in bin/lib/guides.js. The build fails on a missing summary, a stale sectionSummaries key, or a link to an unknown anchor.
• The build deletes and rewrites each references/ directory, so renamed sections never leave orphans. npm run check:skills (scripts/check-skills.js) verifies line limits, that every relative link and anchor resolves, and that every reference file is linked from its SKILL.md. CI runs both and fails on any diff or untracked file under skills/.
• 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.