Immutable. This exact content is served forever at /api/v1/blob/03711b3d395342cb.
# CLAUDE.md `agent-skill-manager` (`asm`) — a TypeScript CLI plus ink/React TUI that manages Agent Skills installed for Claude Code, Codex, Gemini, and OpenClaw. ## Critical commands ```bash npm install # postinstall no-ops when CI or ASM_SKIP_POSTINSTALL is set npm run build # tsx scripts/build.ts -> dist/ (gitignored) CI=true npm test # unit suite — the command of record npm run typecheck # tsc --noEmit npm run lint:site # eslint over website-src/src npm run test:e2e # tests/e2e/ — NOT covered by `npm test` npm start # run the TUI from source ``` `npm test` is `vitest run src/`, and that argument is a **substring filter on the test path**, not a directory — `website-src/src/__tests__/` matches it too, so `npm run test:site` is a subset of `npm test`, not a separate leg. Only `tests/e2e/` is excluded. Measured timings and evidence: `docs/AGENT_ENVIRONMENT.md`. Node and npm must satisfy `package.json` `engines` — node `">=18 <23"`, npm `">=9"`. Mind the upper bound: `CONTRIBUTING.md` and `docs/DEVELOPMENT.md` still state a floor with no ceiling, and `engines` is the one that is correct. ## Architecture map - `bin/agent-skill-manager.ts` — entry point: args go to `src/cli.ts`, none to the TUI. - `src/cli.ts` — ~30 `cmd*` handlers, all output through `src/formatter.ts`. - `src/index.tsx` + `src/views/` — the ink/React TUI. - `src/*.ts` — one module per domain (scanner, installer, auditor, skill-index, …), each with its `*.test.ts` beside it. - `data/skill-index/` — committed per-repo index JSON; generated, never hand-edited. - `website-src/` — site source; `website/` — its published output. - `scripts/` — build, preindex, catalog generation. - Detail: `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT.md`. ## Hard rules - **YOU MUST NOT run `npm run preindex`, `npm run build:website`, or `npm run refresh:repo-bundles` as a probe.** They rewrite tracked files under `data/skill-index/` and `website/`. Run them only when regenerating the catalog is the point of the change, then review the diff. - **IMPORTANT: `npm run preindex` also rewrites the developer's real `~/.config/agent-skill-manager/skill-index/`** — a mutation no git diff shows. - **IMPORTANT: the unit suite writes to the real `~/.config/agent-skill-manager/`.** `src/config.ts` derives that path from `homedir()` at module load with no override, so tests mutate developer state and local results are machine-dependent. `CI=true` sandboxes nothing. - A local failure in `src/skill-index.test.ts` is usually that non-hermeticity, not the change under review. Confirm against CI before "fixing" it. - Never commit `dist/` or `node_modules/`. Most of `website/` is gitignored, but its `*-stats.json` and `robots.txt` are tracked — commit those only on a deliberate regeneration. - Never delete or rewrite untracked scratch files at the repo root; other sessions own them. - Conventional Commits; branch from `main` as `<type>/<issue>-<description>`; PR into `main`. ## Workflow preferences - Iterate with the narrowest runner — `npx vitest run src/<module>.test.ts` — and run `CI=true npm test` only before pushing. - Run `npm run typecheck` after a series of edits; do not wait for the commit hook. - Change `src/<name>.ts` and its `src/<name>.test.ts` together. - Install both hook stages; a plain `pre-commit install` silently skips pre-push: `pre-commit install --hook-type pre-commit --hook-type pre-push`. - Prettier runs on commit — do not hand-format markdown, TS, or JSON to match it. - Keep changes minimal and scoped to the task; do not opportunistically refactor. ## Token Efficiency - Never re-read files you just wrote or edited. You know the contents. - Never re-run commands to "verify" unless the outcome was uncertain. - Don't echo back large blocks of code or file contents unless asked. - Batch related edits into single operations. Don't make 5 edits when 1 handles it. - Skip confirmations like "I'll continue..." Just do it. - If a task needs 1 tool call, don't use 3. Plan before acting. - Do not summarize what you just did unless the result is ambiguous or you need additional input.