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.

Release process

All changes reach main through a pull request. Never push to main directly and never run npm publish locally. Publishing to npm, tagging, and the GitHub release all happen in CI when a PR that bumps the version is merged.

1. Branch: git checkout -b <type>/<short-description> (e.g. docs/seo-llmo-mcp, fix/cli-windows-paths).
2. Edit content - update one or more *-guide.md files (or add a new guide, see below), then rebuild:

   npm run build:skills          # regenerates skills/<name>/SKILL.md and references/

   Commit the guide and the regenerated skills/ files together.
3. Bump the version in the same PR (skip this for changes that should not ship a release, e.g. README or CI tweaks):

   npm version patch             # or minor / major

   The repo .npmrc sets git-tag-version=false, so this only edits files: the version hook runs sync-versions.js (writes the new version to .claude-plugin/plugin.json and marketplace.json) and build-skills.js, then stages them. Add a matching ## vX.Y.Z entry to CHANGELOG.md and commit everything.
4. Open the PR. .github/workflows/ci.yml checks that skills/ matches the guides, that plugin versions match package.json, and, if the version changed, that it is not already on npm and has a CHANGELOG entry. The job summary says whether merging will publish.
5. Merge. .github/workflows/release.yml runs on every push to main. If the package.json version is not on npm yet, it runs npm publish (the prepublishOnly hook rebuilds skills as a safety net), then creates the vX.Y.Z tag and a GitHub release titled vX.Y.Z - <PR title> with the CHANGELOG entry as notes. If the version is already published, it does nothing. The plugin marketplace (/plugin marketplace add ziniman/ai-instruct) reads main directly, so it updates on merge either way.

npm auth uses trusted publishing (OIDC), so there is no NPM_TOKEN secret to rotate and no 2FA prompt. The trusted publisher is configured on npmjs.com under the package settings: GitHub Actions, repo ziniman/ai-instruct, workflow release.yml. Renaming the workflow file breaks publishing until that setting is updated.

Never bump the version by hand-editing package.json - it skips the sync hook and CI will fail on mismatched plugin versions.

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>/ (and npm run check:skills), then commit it alongside the guide. If the build asks for section summaries, add Applies when: lines to the guide or a sectionSummaries map to its GUIDES entry
6. Add the guide's raw GitHub URL to llms.txt

Changelog

CHANGELOG.md in the repo root tracks all meaningful changes. Update it on every commit that adds, modifies, or removes guide content, CLI behaviour, skills, or plugin metadata. Skip changelog entries for typo fixes, formatting-only changes, and version-bump-only commits.

Format: add a new ## vX.Y.Z · YYYY-MM-DD section at the top with one bold entry per changed area:

## vX.Y.Z  ·  YYYY-MM-DD

**`skill-name`** — One-line description of what changed and why it matters

**`another-skill`** — Another change

Use backtick skill names (seo-llmo, web-accessibility, etc.) or all guides, CLI, README when the change is not skill-specific.

Commit style

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