Add npm README and global skills install helper

Ship packages/cli/README.md for the registry page, know-code skills
--global for cross-repo harness installs, and bump to 0.1.3.

Know-Code-Verified: e40e38dbcda584f35980d61a2d3d29eb73abdc19b264cd23bddd848c0d2d8a37

Author: chtnnh

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.3
+
+### Package
+- Add `packages/cli/README.md` so the npm package page has documentation
+- `know-code skills [--global]` wraps `npx skills add chtnnh/know-code` for project or user-global skill install
+
+### Docs
+- Document global skill install (`--global` / harness home dirs)
+
 ## 0.1.2
 
 ### Package

README.md

@@ -28,7 +28,11 @@ npm i -g @chtnnh/know-code
 npm i -g github:chtnnh/know-code#main:packages/cli
 
 know-code init --level standard --agents claude,cursor,codex --workflow
-npx skills add chtnnh/know-code
+
+# Skills — project only, or global (all repos)
+know-code skills
+know-code skills --global
+# equivalent: npx skills add chtnnh/know-code [--global]
 ```
 
 `init --workflow` adds a GitHub Actions workflow that uses [`chtnnh/know-code/action@v0.1.2`](./action).
@@ -49,6 +53,7 @@ Zed has no PreToolUse-style shell hooks. Rely on git hooks from `know-code init`
 
 ```bash
 know-code init [--level …] [--base-branch main] [--agents …] [--workflow]
+know-code skills [--global] [--agents cursor,claude-code,…]
 know-code status [--json]
 know-code hash [--json]
 know-code check

package.json

@@ -1,7 +1,7 @@
 {
   "name": "know-code-monorepo",
   "private": true,
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "k(no)w-code — agents don't push until you know exactly what's changed",
   "workspaces": [
     "packages/cli",

packages/cli/README.md

@@ -0,0 +1,54 @@
+# @chtnnh/know-code
+
+**Agents don’t push until you know exactly what’s changed.**
+
+CLI that gates `git commit` / `git push` / PR creation until a human passes a browser comprehension quiz about the staged diff. Pair with the [know-code Agent Skills](https://github.com/chtnnh/know-code) in Claude Code, Cursor, Codex, and other agentskills.io harnesses.
+
+**Docs:** [kc.chtnnhfoundation.org](https://kc.chtnnhfoundation.org) · **Repo:** [chtnnh/know-code](https://github.com/chtnnh/know-code)
+
+## Install
+
+```bash
+npm i -g @chtnnh/know-code
+know-code init --level standard --agents claude,cursor,codex --workflow
+```
+
+The npm binary is `know-code` (package name is scoped because unscoped `know-code` collides with `knowcode` on npm).
+
+## Skills (project or global)
+
+```bash
+# This repo / project only
+know-code skills
+# same as: npx skills add chtnnh/know-code
+
+# All repos — install into your user harness dirs (~/.cursor/skills, ~/.claude/skills, …)
+know-code skills --global
+# same as: npx skills add chtnnh/know-code --global
+```
+
+## Everyday commands
+
+```bash
+know-code status
+know-code ask --quiz .know-code/quiz.json
+know-code pass --level standard --hash "$(know-code hash)"
+know-code commit -m "feat: …"    # adds Know-Code-Verified trailer
+know-code verify                 # CI
+```
+
+## CI
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: chtnnh/know-code/action@v0.1.2
+  with:
+    base-branch: main
+```
+
+Or `know-code init --workflow`.
+
+## License
+
+MIT

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chtnnh/know-code",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Gate git push / PR creation until the human passes a comprehension quiz about the diff",
   "type": "module",
   "bin": {

packages/cli/src/commands/init.ts

@@ -121,8 +121,10 @@ export function cmdInit(opts: {
   console.log(`Config written → .know-code/config.json (level: ${config.level})`);
   console.log("");
   console.log("Next steps:");
-  console.log("  1. npm i -g @chtnnh/know-code   # or: npm i -g github:chtnnh/know-code#main:packages/cli");
-  console.log("  2. npx skills add chtnnh/know-code");
+  console.log("  1. npm i -g @chtnnh/know-code");
+  console.log("  2. Skills (pick one):");
+  console.log("       know-code skills              # this repo only");
+  console.log("       know-code skills --global     # all repos (Cursor/Claude/Codex/…)");
   console.log("  3. teach → implement → know-code ask (browser quiz) → know-code pass");
   console.log('  4. know-code commit -m "…"   # adds Know-Code-Verified trailer');
   console.log(`Docs: ${DOCS}`);

packages/cli/src/commands/skills.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+
+const SKILLS_SOURCE = "chtnnh/know-code";
+
+/**
+ * Install know-code + know-code-teach via the agentskills `skills` CLI.
+ * --global puts skills in user harness dirs (e.g. ~/.cursor/skills) so they
+ * apply across all repositories.
+ */
+export function cmdSkills(opts: {
+  global?: boolean;
+  agents?: string;
+  yes?: boolean;
+}): void {
+  const args = ["skills", "add", SKILLS_SOURCE];
+  if (opts.global) args.push("--global");
+  if (opts.yes) args.push("--yes");
+  if (opts.agents) {
+    for (const a of opts.agents.split(",").map((s) => s.trim()).filter(Boolean)) {
+      args.push("--agent", a);
+    }
+  }
+
+  console.log(`know-code: running npx ${args.join(" ")}`);
+  if (opts.global) {
+    console.log(
+      "know-code: global install → user skill dirs (available in every repo for selected harnesses)",
+    );
+  } else {
+    console.log("know-code: project install → .agents/skills (or agent-specific project dirs)");
+  }
+
+  const result = spawnSync("npx", ["--yes", ...args], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  if (result.error) {
+    throw new Error(
+      `Failed to run npx skills: ${result.error.message}\n` +
+        `Install Node/npm, then: npx skills add ${SKILLS_SOURCE}${opts.global ? " --global" : ""}`,
+    );
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+
+  console.log("");
+  console.log("know-code: skills installed.");
+  if (opts.global) {
+    console.log("  Tip: restart or reload the agent window if skills don’t appear yet.");
+    console.log("  List: npx skills ls -g");
+  }
+}

packages/cli/src/index.ts

@@ -5,6 +5,7 @@ import { cmdCommit } from "./commands/commit.js";
 import { cmdHash } from "./commands/hash.js";
 import { cmdInit } from "./commands/init.js";
 import { cmdPass } from "./commands/pass.js";
+import { cmdSkills } from "./commands/skills.js";
 import { cmdStatus } from "./commands/status.js";
 import { cmdVerify } from "./commands/verify.js";
 
@@ -13,6 +14,7 @@ const HELP = `know-code — block commit/push/PR until you can explain the diff
 Usage:
   know-code init [--level lite|standard|deep] [--base-branch main]
                  [--agents claude,cursor,codex] [--require-trailer] [--workflow]
+  know-code skills [--global|-g] [--agents <names>] [--yes]
   know-code check
   know-code pass [--level lite|standard|deep] [--hash <diffHash>]
   know-code ask [--quiz .know-code/quiz.json] [--port 3847] [--timeout 1800] [--no-open]
@@ -109,6 +111,17 @@ function main(): void {
       case "commit":
         cmdCommit(rest[0] === "--" ? rest.slice(1) : rest);
         break;
+      case "skills":
+        cmdSkills({
+          global:
+            flags.global === true ||
+            flags.g === true ||
+            rest.includes("-g") ||
+            rest.includes("--global"),
+          agents: typeof flags.agents === "string" ? flags.agents : undefined,
+          yes: flags.yes === true || flags.y === true || rest.includes("-y"),
+        });
+        break;
       case "help":
       case "--help":
       case "-h":
@@ -117,7 +130,7 @@ function main(): void {
       case "version":
       case "--version":
       case "-v":
-        console.log("0.1.2");
+        console.log("0.1.3");
         break;
       default:
         console.error(`Unknown command: ${command}\n`);

skills/know-code/SKILL.md

@@ -111,7 +111,8 @@ Then push when asked / when shipping.
 ```bash
 npm i -g @chtnnh/know-code
 know-code init --level standard --agents claude,cursor,codex --workflow
-npx skills add chtnnh/know-code
+know-code skills              # project
+know-code skills --global     # all repos
 ```
 
 Docs: https://kc.chtnnhfoundation.org

website/docs/cli.md

@@ -14,6 +14,7 @@ npm i -g @chtnnh/know-code
 | Command | Purpose |
 |---------|---------|
 | `know-code init` | Config, git hooks; optional `--agents`, `--workflow` |
+| `know-code skills [--global]` | Install Agent Skills (project or user-global) |
 | `know-code status [--json]` | Gate status, hash, range |
 | `know-code hash [--json]` | Print current index hash |
 | `know-code check` | Exit 0 allow / 2 block |