Keep your docs index in sync automatically. When you add or change Markdown files under docs/, a pre-commit hook (or CI step) updates the index table—no manual edits, no forgotten entries.

• Zero config for common setups: docs/README.md index, exclude archive/, optional warning for root-level .md
• Composable: Use with Husky or plain .git/hooks/pre-commit
• CI-friendly: docs-index-keeper check exits 1 if the index would change (enforce “index must be up to date”)
• Portable: Node 18+, no runtime dependencies, works with npm / pnpm / yarn / bun

Why use it?

| Problem | What docs-index-keeper does | |--------|-----------------------------| | New runbooks or guides get added under docs/ but nobody updates the index | Pre-commit (or CI) adds a row to docs/README.md automatically | | Contributors forget to touch the index | Hook runs on staged .md files; index is updated and re-staged in the same commit | | “Is this doc listed?” is a recurring review comment | Index stays in sync by construction | | Onboarding: “Where do I find X?” | Single table in docs/README.md is always up to date |

ROI: A few minutes to run npx docs-index-keeper init once. After that, you avoid repeated manual index edits and review back-and-forth every time someone adds a doc. The index becomes a reliable map of your docs without extra process.

Quick start

# In your repo root (with a docs/ folder and docs/README.md index table)
npm install -D docs-index-keeper
npx docs-index-keeper init

Then, when you git add docs/my-new-guide.md and commit, the hook will run docs-index-keeper update and add the new row to docs/README.md (and stage it).

AI skill / marketplace readiness

This repository now includes a root SKILL.md, which makes the project usable as an agent skill definition for skill-aware tools and registries that scan repository contents.

What is included here:

• SKILL.md with trigger phrases, workflow, config, and validation
• richer Agent Skills metadata (license, compatibility, metadata)
• a minimal Cursor plugin wrapper in .cursor-plugin/plugin.json
• a Cursor skill layout in skills/docs-index-keeper/SKILL.md
• npm package metadata that ships SKILL.md and usage examples
• copy-pasteable prompts for agent tools in examples/skill-usage.md
• a platform support note in docs/agent-platforms.md

What may still be needed:

• some marketplaces require their own registry entry, plugin manifest, or catalog submission flow in addition to a repo-level SKILL.md
• Cursor Marketplace publication still requires an actual plugin submission flow
• if a directory or marketplace expects a different metadata schema, add that schema on top of this repo rather than replacing SKILL.md

AI usage examples

Codex

Install docs-index-keeper in this repository, configure it for docs/README.md, add the pre-commit hook, and verify the setup.

Use docs-index-keeper to update the docs index for the currently staged Markdown files and show me which rows were added.

Claude

Set up docs-index-keeper in this repo so new docs under docs/ are automatically added to docs/README.md during pre-commit. Keep the default archive exclusion.

Use the docs-index-keeper workflow in this repository to add docs/runbooks/oncall.md into the docs index and explain any assumptions briefly.

Cursor

Add docs-index-keeper to this project, wire the hook, and make CI fail if docs/README.md is missing entries for docs Markdown files.

Platform support

• Codex: SKILL.md plus AGENTS.md
• Claude / Claude Code: SKILL.md plus repo-local guidance
• Cursor: SKILL.md plus a minimal plugin manifest in .cursor-plugin/plugin.json

Details: docs/agent-platforms.md

More examples: examples/skill-usage.md

Marketplace submission checklist: docs/marketplace-submissions.md

Commands

| Command | Purpose | |--------|---------| | docs-index-keeper init | Add a pre-commit hook (Husky or .git/hooks/pre-commit) that runs update and stages the index file | | docs-index-keeper update | Update the index from staged .md files (used by the hook) | | docs-index-keeper check | Dry run; exit 1 if the index would change (use in CI to require an up-to-date index) | | docs-index-keeper add <path|mask...> | Add one or many files to the index (e.g. docs-index-keeper add docs/runbook.md docs/plans/*.md) |

Add One, Many, or by Mask

add supports direct file paths and glob-like masks in one command.

# one file
docs-index-keeper add docs/runbook.md

# many files
docs-index-keeper add docs/runbook.md docs/guides/oncall.md

# mask (quote masks so your shell does not expand unexpectedly)
docs-index-keeper add "docs/plans/*.md"

# mixed
docs-index-keeper add docs/README.md "docs/plans/*.md"

Notes:

• only Markdown files are added
• excluded paths are skipped based on config
• already-indexed files are skipped
• the command prints both added and skipped entries

Config

Put config in package.json or in .docs-index-keeper.json at the repo root.

Example (package.json):

{
  "docsIndexKeeper": {
    "indexFile": "docs/README.md",
    "docsDir": "docs",
    "exclude": ["README.md", "archive/"],
    "allowedRootMd": ["README.md", "AGENTS.md", "CONTRIBUTING.md"],
    "warnRootMd": true
  }
}

• indexFile — Path to the Markdown file that contains the index table (default: docs/README.md).
• docsDir — Directory treated as “docs” (default: docs).
• exclude — Paths under docsDir that are not added (e.g. README.md, archive/).
• allowedRootMd — Root-level .md files that do not trigger a warning when changed.
• warnRootMd — If true, warn when new/changed .md in repo root (or .github/) are staged; suggests moving them to docs/.

Index format

The index file should contain a Markdown table with a header like | Doc | Purpose |. New rows are inserted before a “sentinel” row (e.g. | [archive/](archive/) | … |) or at the end of the table. The title for the link is taken from the filename; the purpose column uses the first # heading in the file, or a slugified filename.

CI: require index up to date

# .github/workflows/docs-index-check.yml
- run: npm ci
- run: npx docs-index-keeper check

Use DOCS_INDEX_KEEPER_STAGED to simulate staged files (e.g. in tests or CI):

DOCS_INDEX_KEEPER_STAGED="docs/foo.md" npx docs-index-keeper check

Releases (maintainers)

Publishing is fully automated in GitHub Actions.

• Push a Conventional Commit to main for a stable release.
• Push a Conventional Commit to beta for an installable npm pre-release published on the beta dist-tag.
• Every push to main or beta first runs a release-readiness job that validates NPM_TOKEN and dry-runs semantic-release before the actual publish step runs.

One-shot: create repo, commit, push (no local npm publish):

./publish.sh

Run from the package root. Requires git, gh (logged in), and npm. Overrides: PROJECT_DIR, REUSE_REMOTE_REPO=true, COMMIT_MSG="...". After push, CI performs the npm publish.

• Versioning: Use Conventional Commits: feat: → minor, fix: → patch, BREAKING CHANGE: (or feat!: / fix!:) → major.
• Pre-releases: The beta branch publishes versions like 1.2.0-beta.1. Install with npm install docs-index-keeper@beta.
• Changelog: CHANGELOG.md is generated and maintained by the release workflow. Do not edit it manually.
• Secrets: In the repo’s GitHub Settings → Secrets and variables → Actions, add NPM_TOKEN (npm token with Read and write for your packages). Paste the token with no trailing newline or space. Use scripts/set-npm-token-secret.sh --from-browser after creating a token at https://www.npmjs.com/settings/~/tokens (Granular). GITHUB_TOKEN is provided by Actions.
• Local verification: Run npm run release:dry-run to validate the semantic-release setup locally without publishing.

Publishing to GitHub Package Registry (instead of npm): Use a scoped name in package.json (e.g. @oleg-koval/docs-index-keeper) and add "publishConfig": { "registry": "https://npm.pkg.github.com" }. In CI, set the secret to a GitHub PAT with write:packages and use it as NPM_TOKEN (semantic-release/npm uses NPM_TOKEN for any registry). Install from GitHub: npm install @oleg-koval/docs-index-keeper with .npmrc: @oleg-koval:registry=https://npm.pkg.github.com.

License

MIT © Oleg Koval