version: "1.0.0"

generated by aix

name: repo-tooling-pro description: >+ "Production-grade repository tooling for this devkit: Node/TypeScript CLI (dist/tools.js) for KB batch queries, skill inventory, validation, KB build/verify, skill-index generation, project indexing, and wiki generation — plus system model (repo-root workspace, skills vs KB artifact lifecycles, batch query execution), failure modes (wrong cwd, missing dist, stale embeddings/index, OOM batch, interrupted builds), decision trade-offs (batch vs single query, when to rebuild KB, analyze depth, CI vs local), and quality guardrails (canonical scripts/README, no invented flags, reproducible Node/commit)."

Use this skill when the user runs or wires CI for build-kb, query-kb, query-kb-batch, verify-kb, list-skills, validate-skills, analyze-skills, build-skill-index, index-project, generate-wiki; asks how to speed up multiple KB queries; needs a JSON list of bundled skills; or wants automation reports for skills vs scripts/ helpers.

Combine with `skills-self-review-pro` for bundle audits, `ci-cd-pro` for pi x-kind: domain x-version: 0.1.0 x-tags: [] x-roles: [] x-compatible: [claude, cursor, codex, gemini] aliases: [repo-tooling]

Repo tooling (professional)

Skill text is English; answer in the user’s preferred language when rules or the conversation specify it.

Official command list: [`scripts/README.md`](/scripts/README.md) at repo root. This skill encodes artifact lifecycles (skills vs KB), batch vs single query economics, and safe automation defaults — not domain skill content (`*-pro` skills stay separate). Confirm repo root cwd, `npm install`, `npm run build` when dist/ is absent, and `config.md` / `config.example.md` for KB paths.

Boundary

`repo-tooling-pro` owns this repository’s CLI (dist/tools.js), when to run validate/build/query commands, and performance/staleness of embeddings and skill index. `ci-cd-pro` owns pipeline YAML and org runner policy. `skills-self-review-pro` owns authoring narrative and checklist depth beyond raw analyze-skills output.

Related skills (this repo)

When to use

• Many KB questions in one session — `query-kb-batch` vs N× `query-kb`.
• `validate-skills` / `build-skill-index` after skill changes.
• `build-kb` → `verify-kb` after document corpus changes.
• `index-project`, `generate-wiki`, `list-skills --json`, performance of RAG batch jobs.
• Explaining OOM, cwd, missing dist/, or stale index behavior.

When not to use

• Writing domain skill content (React, Postgres, etc.) — use the relevant `*-pro` skill; use `repo-tooling-pro` only for tooling steps that support authoring.
• General Git tutorial without this CLI — `git-operations-pro`.
• Product KB content authoring — writing docs is not the same as choosing `build-kb` flags.

Required inputs

• Whether cwd is repo root (or path to use).
• Whether `dist/` exists or CI must `npm run build` first.
• Approximate batch size / RAM for large `query-kb-batch` jobs.

Expected output

Follow Suggested response format strictly — system model through residual risks.

Workflow

Apply Karpathy principles throughout: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution.

1. Confirm cwd, Node install, dist/tools.js presence; read `scripts/README.md` for exact flags. → verify: [context documented].
2. State assumptions about requirements, constraints (Think Before Coding).
3. Apply minimum solution first; escalate only when justified (Simplicity First).
4. Make surgical changes — only touch code directly related to the request (Surgical Changes).
5. Define success criteria; loop until verified (Goal-Driven Execution).
6. Respond using Suggested response format; note main risks.

Operating principles

1. Think Before Coding — Confirm repo root, built artifacts, and the actual command goal before suggesting tooling steps. Ask when the user may be outside the repo or using stale artifacts.
2. Simplicity First — Use the smallest command sequence that proves the state. Do not rebuild KB, graphs, or indexes unless the relevant source changed.
3. Surgical Changes — Touch only the tooling command, script, or artifact lifecycle relevant to the request. Do not broaden into unrelated repo cleanup.
4. Goal-Driven Execution — Done = the command path is reproducible, the expected artifact state is explicit, and verification confirms the tool outcome.
5. Repo root matters — Many failures are simply wrong cwd or missing build output; check those before deeper debugging.
6. Artifact lifecycles are separate — Skills index, KB embeddings, project index, and dist build are different pipelines with different rebuild triggers.
7. Do not invent flags — All command examples must map to real CLI behavior documented in repo scripts.
8. Performance advice needs context — Batch size, RAM, and cold-start economics matter before claiming one query mode is “better.”

Default recommendations by scenario

• Skill content changed — validate-skills then build-skill-index; skip build-kb unless docs changed.
• KB docs changed — build-kb then verify-kb, and query only after artifacts refresh.
• Many local questions — Prefer query-kb-batch over repeated single queries.
• Missing `dist/` — Build first before assuming command bugs.

Decision trees

Summary: choose the right command path based on which source-of-truth changed and whether the issue is artifact state, cwd, or scale/performance.

Details: references/decision-tree.md

Anti-patterns

Summary: rebuilding everything by reflex, running commands from the wrong cwd, inventing unsupported flags, and diagnosing stale artifacts as code bugs.

Details: references/anti-patterns.md

Repo tooling and KB lifecycle system model (summary)

How source files, built CLI, skill index, and KB artifacts relate so rebuild decisions stay precise.

Details: references/repo-tooling-and-kb-lifecycle-system-model.md

KB and repo scripts (summary)

What each command actually does and when it should or should not be run.

Details: references/kb-and-repo-scripts.md

Failure modes and mitigation (summary)

Wrong cwd, missing dist/, stale indexes, OOM batches, and broken assumptions about artifact freshness.

Details: references/failure-modes-detection-mitigation.md

Versions (summary)

Version notes that affect Node compatibility, CLI behavior, and supported command expectations.

Details: references/versions.md

Suggested response format

1. Context — cwd, artifact state, Node/build status, and the command goal.
2. Tooling model — Which lifecycle or artifact is involved and why.
3. Recommendation — Minimum command sequence or fix path.
4. Verification — Exact command/output checks that prove the tool state is correct.
5. Residual risks — Remaining stale-artifact, environment, or performance caveats.

Resources in this skill

Quick example

Input: "I changed a skill and want the repo state updated correctly."

• Run the smallest relevant pipeline: validate skill metadata, then rebuild skill index.
• Do not rebuild KB unless docs or KB corpus changed.
• Verify: Validation passes and the updated skill appears in the index artifact.

Input (tricky): "query-kb is slow when I ask ten questions in a row."

• Prefer query-kb-batch to avoid repeated model loads.
• Check memory constraints before assuming parallel single queries are cheaper.
• Verify: The batch command returns all results with fewer repeated cold starts.

Input (cross-skill): "Our CI job for skill validation keeps failing after a docs-only change."

• Pair `ci-cd-pro` for workflow wiring, and use `repo-tooling-pro` to separate which artifacts really need rebuilding.
• Remove unnecessary steps before debugging imaginary command bugs.
• Verify: CI only runs the commands justified by the changed files and passes reproducibly.

Checklist before calling the skill done

• [ ] Repo root, build state, and actual command goal confirmed first (Think Before Coding)
• [ ] Minimum command sequence chosen; no unnecessary rebuilds added (Simplicity First)
• [ ] Only the relevant tooling/artifact lifecycle was touched (Surgical Changes)
• [ ] Success criteria and command verification are explicit and validated (Goal-Driven Execution)
• [ ] Command examples map to real CLI behavior
• [ ] Artifact rebuild triggers are correctly distinguished
• [ ] Performance guidance is tied to batch size or environment context where relevant
• [ ] Remaining environment or stale-artifact caveats are documented