# Ki Repo Tools > Audit, conform, or scaffold a Knowledge Islands `tools-*` repo — ONE standalone CLI per repo, distributed by a `curl | bash` installer and companion Homebrew formula. Governs shared shape and public conventions language-agnostically: executable + bit, installer, version/release, changelog, CI, help/errors/status, one documented `completion ` action, and optionally installed/linkable portable-roff `man/.1`. Conditionals: shell → shellcheck + bats; physical manual → mandoc CI; package.json → `ki-engineering`. Triggers: "audit this tool repo", "scaffold a CLI tool", "release a command-line tool", "does this tools- repo follow our standard", "check my tools- repo". Off-ramps: tap/formula → `ki-repo-homebrew-tap`; README/LICENSE/GitHub settings → `ki-repo`; TS/Bun toolchain → `ki-engineering`. Not individual tool behaviour. - Skill: `knowledgeislands/ki-repo-tools` (Agent Skill, multi-file: 21 files) - Install (CLI): `npx skillmds@latest add knowledgeislands/ki-repo-tools` - Raw SKILL.md: https://api.skillmd.com/api/skills/knowledgeislands/ki-repo-tools/raw - Safety review: WARNING - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: knowledgeislands (https://skillmd.com/u/knowledgeislands) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/knowledgeislands/ki-repo-tools --- # Knowledge Islands tool-repo standard You are helping audit, conform, or scaffold a **`tools-*` repo** — a repo holding exactly **one** standalone command-line tool, distributed two ways: a `curl | bash` installer at the repo root, and a companion Homebrew formula that lives in the tap. [`tools-mgit`](https://github.com/knowledgeislands/tools-mgit) (Bash) and [`tools-ki`](https://github.com/knowledgeislands/tools-ki) (TypeScript/Bun) are the reference implementations. The standard governs shared shape and public interface conventions, not a language or the tools' individual behaviour. This skill rides on `ki-repo` (local files, GitHub settings) but **not** `ki-engineering` — a bash tool has no TypeScript/Bun toolchain to govern, so no `ki-engineering` declaration is assumed (the same pattern `ki-repo-kb` follows). If the tool grows a `package.json`, that changes: it then declares `[skills.ki-engineering]` too and defers its lint/test there (see the capability rule below). The full, quotable standard lives in [the tool-repository standard](references/standards-tool-repositories.md); the line-by-line pass/fail items live in [the generated rubric](references/rubric.md). `ki repo audit` and `ki repo conform` inspect the structured mechanical contract directly through the host. They never execute a target binary, installer, package manager, CI workflow, or network validator; runtime and release evidence are explicit separate diagnostics. ## Container, not contents This skill judges the **container** and a small shared public interface — not the quality of the tool's own implementation: - **In scope:** the `bin/` layout and its exec bit, `install.sh`, local release-marker shape, `CHANGELOG.md`, CI source shape, test-suite presence, completion, manual authoring and distribution, and the capability conditionals below. Runtime `--version`, installer, CI, and release execution remain separate evidence. - **Out of scope:** whether tool-specific operations are correct, well-factored, or fast. That is the tool author's concern (and, for a shell tool, shellcheck + bats — which this skill checks are _wired_, not what they _find_). The Homebrew tap and its formula are `ki-repo-homebrew-tap`'s; the repo's README, LICENSE, and GitHub settings are `ki-repo`'s. ## The canonical shape at a glance ```text tools-/ ├── bin/ # THE executable — chmod +x (git tracks the exec bit). Answers --version. ├── install.sh # curl installer: honours env overrides (target dir + version), verifies the │ # download, is idempotent, and publishes/links a manual when one exists. ├── tests/ or src/tests/ # executable test suite (a *.bats suite under tests/ for a shell tool). Expected. ├── .github/workflows/*.yml # CI: lint + test on every push. Expected. ├── man/.1 # Optional manual source; when present, CI runs mandoc -T lint. ├── CHANGELOG.md # semver release history or a declared current-release baseline. ├── README.md · LICENSE # ki-repo's job — not governed here. └── .ki.toml # carries qualified ki-repo + ki-repo-tools declarations (the opt-in marker). ``` `bin/` with ≥1 executable file is the only hard requirement (**FAIL** if missing); everything else is **WARN** — expected but not ship-stopping. The companion Homebrew formula lives in the tap repo (`homebrew-`, `Formula/.rb`), governed by `ki-repo-homebrew-tap` — cross-reference it, don't reproduce it. ## The capability-conditional rule Mirrors `ki-engineering`'s capability-conditional pattern: what the repo _is_ decides which checks apply, so the same standard covers a bash tool and a TS tool without forking. - **Shell entrypoint** (the primary `bin/` file has a `bash`/`sh` shebang): it MUST be shellcheck-clean in CI (a workflow references `shellcheck`) and ship a `bats` suite that CI runs (a `*.bats` file under `tests/` and a workflow that references `bats`). - **A `package.json` appears** (a TS/Bun tool): the repo defers lint/test to `ki-engineering` and MUST also declare `[skills.ki-engineering]` in its `.ki.toml`. The shell checks don't apply. - **A physical `man/.1` page appears**: CI MUST run `mandoc -T lint man/.1`, directly or through the repository's native task runner. The release installer and its `--link` mode publish or link that manual alongside the executable. - **Another language** (Python, Go, …): defer to that language's own toolchain; the container checks (bin, install.sh, versioning, changelog, CI, tests) still apply. ## The qualified `ki-repo-tools` marker A `tools-*` repo opts into this standard by declaring a **keyless** `[skills.ki-repo-tools]` table in its `.ki.toml`. The table is validated **down** (this skill reads only its own table and warns on any unknown key inside it). `ki-repo` owns selecting the declaration; this skill may only set executable bits on verified physical `bin/*` files and `install.sh`. Missing content, malformed or unsafe paths, external releases, and Homebrew operations remain report-only. ## Release readiness Before preparing or reviewing a tool release, read [the release-readiness checklist](references/standards-release-readiness.md). It consolidates the existing version, documentation, validation, and distribution obligations into one staged human checklist; it does not create another skill mode or take ownership from `ki-engineering` or `ki-repo-homebrew-tap`. ## Operating modes Every governance skill carries the universal four **AUDIT · CONFORM · EDUCATE · REFRESH**; EDUCATE here scaffolds a new tool repo. Invoked as `help` / `-h` / `?`, it explains itself and stops — the generated HELP block (name, purpose, invocation, modes, off-ramps), taking no action. With no mode it does the same, then, in an interactive session only, offers the mode choice via `AskUserQuestion`, prompting for any `argument-hint` target the chosen mode shows. The four procedures remain on demand because each coordinates work outside the hosted catalogue: AUDIT and CONFORM sequence `ki-repo`, the conditional `ki-engineering` layer, and explicit release checks; EDUCATE scaffolds a new repository; REFRESH reconciles moving external specifications. Each file owns one mode so invoking one never loads an unrelated procedure. ### Mode AUDIT → Read [references/mode-audit.md](references/mode-audit.md) ### Mode CONFORM → Read [references/mode-conform.md](references/mode-conform.md) ### Mode EDUCATE → Read [references/mode-educate.md](references/mode-educate.md) ### Mode REFRESH → Read [references/mode-refresh.md](references/mode-refresh.md) ### Mode HELP Invoked as `help`, `-h`, or `?`, explain the skill, invocation, modes, capability conditionals, and off-ramps, then stop. With no recognisable mode, provide the same explanation and only offer a mode choice in an interactive session. ## Notes - The standard is anchored to `tools-mgit` and `tools-ki`, plus external specs (shellcheck, bats, keep-a-changelog, semver, XDG) — the tracked [source list](references/sources.md) records them; Mode REFRESH re-fetches on the declared cadence. - Refer to another skill by its `name` (`ki-repo`, `ki-engineering`, `ki-repo-homebrew-tap`), never a file path — skills are relocatable. - Hosted execution carries no private checker, reporter, or compatibility wrapper. The skill intentionally has no top-level public script; its executable governance surface is `scripts/rubric/items/index.ts`, loaded directly by `ki`. - No `exemplars.md` is bundled: the canonical tree and capability table above, plus the complete installer and release guidance in the standard, already illustrate the reusable shapes; a separate exemplar would duplicate them.