skissue 0.1.11 → 0.1.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skill-issue contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,132 +1,436 @@
-# skissue
+<pre align="center">
+  ▗▄▄▖▗▖ ▗▖▗▄▄▄▖▗▖   ▗▖
+  ▐▌   ▐▌▗▞▘  █  ▐▌   ▐▌
+  ▝▀▚▖ ▐▛▚▖   █  ▐▌   ▐▌
+  ▗▄▄▞▘▐▌ ▐▌▗▄█▄▖▐▙▄▄▖▐▙▄▄▖
+  ▗▄▄▄▖▗▄▄▖▗▄▄▖▗▖ ▗▖▗▄▄▄▖
+    █  ▐▌   ▐▌   ▐▌ ▐▌▐▌
+    █   ▝▀▚▖ ▝▀▚▖▐▌ ▐▌▐▛▀▀▘
+  ▗▄█▄▖▗▄▄▞▘▗▄▄▞▘▝▚▄▞▘▐▙▄▄▖
+</pre>
+
+<h3 align="center">
+  A package manager for AI agent skills.<br>
+  <sub>Install. Sync. Ship. No skill issues here.</sub>
+</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/skissue"><img src="https://img.shields.io/npm/v/skissue?style=flat-square&logo=npm&color=CB3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/skissue"><img src="https://img.shields.io/npm/dm/skissue?style=flat-square&logo=npm&color=CB3837" alt="npm downloads"></a>
+  <a href="https://github.com/midyan/skill-issue/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License MIT"></a>
+  <a href="https://github.com/midyan/skill-issue"><img src="https://img.shields.io/github/stars/midyan/skill-issue?style=flat-square&logo=github&color=8B5CF6" alt="GitHub stars"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen?style=flat-square&logo=nodedotjs" alt="Node 24+">
+  <img src="https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript" alt="TypeScript">
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#create-your-own-registry">Create a Registry</a> ·
+  <a href="#ci--automation">CI & Automation</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## What is this?
+
+**skissue** is a CLI that installs and syncs **agent skills** from a Git-based registry into your project. Think of it as npm, but for AI agent capabilities — soft docs (`SKILL.md`) and optional hard checks (`hard/index.ts`) that your coding agents can discover and use automatically.
 
-CLI to **install and sync agent skills** from a **GitHub registry** or a **local directory** (e.g. a monorepo whose root contains **`registry/`** and **`registry.json`**). On the **consumer**, skills are installed under **`skillsRoot`** (default **`.agents/skills/<skill-id>/`**, each with **`SKILL.md`**). Configuration and lock state live under **`.skill-issue/`** (committable; no secrets).
+```
+your-project/
+├── .agents/skills/          ← skills land here
+│   ├── validate-commits/
+│   │   ├── SKILL.md         ← agent reads this
+│   │   └── hard/
+│   │       └── index.ts     ← CI runs this
+│   ├── code-review/
+│   │   └── SKILL.md
+│   └── ...
+├── .skill-issue/
+│   ├── config.yaml          ← registry pointer
+│   └── lock.json            ← pinned versions
+└── your code...
+```
 
-**This repository** contains the **CLI** (`src/`) and a **harness** (`harness/`) — TypeScript checks for this repo's docs, indexes, and `src/` layout. The **hosted skill catalog** (`registry.json` + `registry/<skill-id>/`) lives in the separate **skill-registry** repository. **`.agents/`** holds **agent rules** and mirrored skill docs for this repo only — it is **not** the installable registry.
+Your agents get superpowers. Your CI gets guardrails. You get coffee.
 
-## Structure
+---
 
-| Path                   | Role                                                                                           |
-| ---------------------- | ---------------------------------------------------------------------------------------------- |
-| [AGENTS.md](AGENTS.md) | Agent entry point                                                                              |
-| [harness/](harness/)   | CI checks (`harness/runner.ts`, `npm run check:all`); see [harness/INDEX.md](harness/INDEX.md) |
-| [.agents/](.agents/)   | Rules for maintaining this repo (not the skill-registry payload)                               |
-| [docs/](docs/)         | Harness (`HARNESS.md`), architecture (`ARCHITECTURE.md`), INDEX format                         |
-| [src/](src/)           | skissue CLI source                                                                             |
-| [scripts/](scripts/)   | `install.sh` for global install from a clone                                                   |
+## Quick Start
 
-## Requirements
+### 1. Install
 
-- **Node** 24+ (see `.nvmrc`)
-- **git** on your `PATH`
-- For **remote** registries: access via **`GITHUB_TOKEN`** / **`GH_TOKEN`**, or **git credentials** / **`gh auth`**. **Local** registries need no network auth.
+```bash
+# Just run it — no global install needed
+npx skissue
+
+# ...or install globally if you're the committed type
+npm install -g skissue
+```
 
-## Install the CLI
+### 2. Initialize
+
+Run `skissue` with no arguments. If no config exists, it walks you through setup interactively:
 
 ```bash
-npx skissue --help
+cd your-project
+npx skissue
 ```
 
-Or install globally:
+```
+  ▗▄▄▖▗▖ ▗▖▗▄▄▄▖▗▖   ▗▖
+  ▐▌   ▐▌▗▞▘  █  ▐▌   ▐▌
+  ▝▀▚▖ ▐▛▚▖   █  ▐▌   ▐▌
+  ▗▄▄▞▘▐▌ ▐▌▗▄█▄▖▐▙▄▄▖▐▙▄▄▖
+  ▗▄▄▄▖▗▄▄▖▗▄▄▖▗▖ ▗▖▗▄▄▄▖
+    █  ▐▌   ▐▌   ▐▌ ▐▌▐▌
+    █   ▝▀▚▖ ▝▀▚▖▐▌ ▐▌▐▛▀▀▘
+  ▗▄█▄▖▗▄▄▞▘▗▄▄▞▘▝▚▄▞▘▐▙▄▄▖
+
+◆  Where does the skill registry live?
+│  ● GitHub — clone registry from owner/repo
+│  ○ Local directory
+└
+```
+
+Pick GitHub or local, point it at your registry, and you're done. Config lands in `.skill-issue/config.yaml`.
+
+### 3. Install skills
 
 ```bash
-npm install -g skissue
-skissue --help
+# Interactive — browse, toggle, install
+npx skissue manage
+
+# Direct — you know what you want
+npx skissue install validate-commits
+npx skissue install code-review
 ```
 
-With no arguments, **`npx skissue`** runs interactive **setup** (`.skill-issue/config.yaml`) if needed, then opens the **manage** menu to install or remove skills.
+### 4. There is no step 4
+
+Skills are in `.agents/skills/`. Your agents can find them. Commit the folder. Ship it.
+
+---
+
+## Commands
+
+| Command                  | What it does                                                 |
+| ------------------------ | ------------------------------------------------------------ |
+| `skissue`                | Smart default — runs `init` if needed, then opens `manage`   |
+| `skissue init`           | Interactive config setup (`.skill-issue/config.yaml`)        |
+| `skissue init-registry`  | Scaffold a minimal registry (`registry.json` + sample skill) |
+| `skissue manage`         | TUI to browse, install, and uninstall skills                 |
+| `skissue install <id>`   | Install a specific skill from the registry                   |
+| `skissue uninstall <id>` | Remove a skill and its lock entry                            |
+| `skissue list`           | Show installed skills with lock metadata                     |
+| `skissue outdated`       | Check which installed skills have newer versions             |
+| `skissue update [id]`    | Re-fetch skill(s) from the registry                          |
+| `skissue doctor`         | Health check — Node version, config, registry connectivity   |
+
+> `manage` is also aliased as `skissue browse`.
+
+---
+
+## Create Your Own Registry
+
+A skill registry is just a Git repo with a specific layout. Here's how to build one from scratch.
+
+**Shortcut:** run `npx skissue init-registry` to create `registry.json`, `registry/<sample-skill>/SKILL.md`, and optionally `git init` in the current directory or a path you choose.
+
+### Registry structure
+
+```
+your-skill-registry/
+├── registry.json              ← manifest of all skills
+└── registry/
+    ├── my-first-skill/
+    │   ├── SKILL.md           ← required: what the skill does
+    │   └── hard/              ← optional: executable checks
+    │       ├── SKILL.md
+    │       └── index.ts
+    ├── another-skill/
+    │   └── SKILL.md
+    └── ...
+```
 
-### From source
+### Step 1: Create the repo
 
 ```bash
-git clone https://github.com/midyan/skill-issue.git
-cd skill-issue
-npm install
-npm run build
-node dist/entry.js --help
+mkdir my-skill-registry && cd my-skill-registry
+git init
+mkdir -p registry
 ```
 
-**Automated publish (CI):**
+### Step 2: Write `registry.json`
 
-1. **Pull requests:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs **`npm run verify`** (TypeScript, ESLint, Prettier, tests, harness, build).
-2. **Push to `main`:** Same **verify** runs unless the commit message contains **`[skip ci]`** (used by the automated version bump so the full suite does not run twice for that commit).
-3. When **CI succeeds** after a push to **`main`**, [`.github/workflows/version-and-release.yml`](.github/workflows/version-and-release.yml) bumps the **patch** version, commits to **`main`** with **`[skip ci]`**, then creates a **GitHub Release** and tag **`v<version>`**. That tag triggers [`.github/workflows/publish.yml`](.github/workflows/publish.yml) to **`npm publish --provenance --access public`** to the public npm registry.
+This is the manifest. It maps skill IDs to their paths:
+
+```json
+{
+  "skills": {
+    "my-first-skill": "registry/my-first-skill",
+    "another-skill": "registry/another-skill"
+  }
+}
+```
 
-**Branch protection:** `GITHUB_TOKEN` must be allowed to **push to `main`** and create releases (or use a PAT with `contents: write` stored as a secret). If publish fails after the tag exists, **re-run** the publish workflow or use **workflow dispatch** with the tag (e.g. `v0.1.0`).
+> If `registry.json` is missing or doesn't list a skill, the convention `registry/<id>/` is used as a fallback.
 
-## Quick start
+### Step 3: Create a skill
 
-### Consumer project + GitHub registry
+Every skill needs at minimum a `SKILL.md` at its root:
 
 ```bash
-cd your-consumer-repo
-skissue init   # choose "GitHub" and enter owner/repo
-skissue install skill-issue
+mkdir -p registry/my-first-skill
+```
+
+```markdown
+<!-- registry/my-first-skill/SKILL.md -->
+
+# My First Skill
+
+Teaches the agent how to do something awesome.
+
+## When to use
+
+Use this skill when the user asks to do the awesome thing.
+
+## Instructions
+
+1. Do the awesome thing
+2. Do it well
+3. Profit
 ```
 
-### Local skill-registry checkout
+### Step 4: (Optional) Add a hard check
 
-Point **`registry.path`** at a clone of **skill-registry** (or another repo whose root has **`registry.json`** and **`registry/`**):
+Hard skills are executable TypeScript that can validate, lint, or enforce rules:
 
 ```bash
-cd /path/to/your-consumer
-npm run dev -- init    # choose "Local directory", path ../skill-registry
-skissue install skill-issue
+mkdir -p registry/my-first-skill/hard
 ```
 
-`registry.path` is **relative to the consumer project root** (where `.skill-issue/` lives). The local registry must be a **git** checkout so `HEAD` can be stored in the lockfile.
+```typescript
+// registry/my-first-skill/hard/index.ts
+const errors: string[] = [];
 
-`init` writes `.skill-issue/config.yaml` (either **`registry.path`** or **`registry.owner` / `registry.repo`**, optional **`registry.useSsh`**, branch, and skills root). `install` resolves the path from **`registry.json`** (or **`registry/<id>`** by convention), copies into **`skillsRoot/<id>/`**, and updates **`.skill-issue/lock.json`**.
+// Your validation logic here
+if (!someCondition) {
+  errors.push("Something is wrong");
+}
 
-**Remote transport (auto):** if **`registry.useSsh`** is omitted, the CLI uses **SSH** (`git@github.com:…`) when **`GITHUB_TOKEN` / `GH_TOKEN` are unset** (typical laptop with GitHub SSH keys), and **HTTPS with a token** when a token is set (CI). Set **`registry.useSsh: true`** or **`false`** to force SSH or HTTPS.
+if (errors.length > 0) {
+  console.error(errors.join("\n"));
+  process.exit(1);
+}
+console.log("All good!");
+```
 
-## Environment
+### Step 5: Push and connect
 
-| Variable       | Purpose                                                                             |
-| -------------- | ----------------------------------------------------------------------------------- |
-| `GITHUB_TOKEN` | HTTPS auth when the resolved transport is HTTPS (e.g. CI, or auto when this is set) |
-| `GH_TOKEN`     | Same as above if `GITHUB_TOKEN` is unset                                            |
+```bash
+git add -A && git commit -m "feat: initial skill registry"
+git remote add origin git@github.com:you/my-skill-registry.git
+git push -u origin main
+```
 
-Do not put tokens in `config.yaml`; keep them in the environment or credential helper.
+Now in any consumer project:
 
-## Registry layout (in the registry repo)
+```bash
+npx skissue init        # choose GitHub, enter you/my-skill-registry
+npx skissue manage      # browse and install your skills
+```
 
-- **`registry.json`** at the **repository root** maps skill ids to paths (typically under **`registry/`**):
+That's it. You're running a skill registry.
 
-```json
-{
-  "skills": {
-    "my-skill": "registry/my-skill"
-  }
-}
+---
+
+## Local Registry (monorepo friendly)
+
+If your registry lives on disk (monorepo, or a local clone), skip GitHub entirely:
+
+```bash
+npx skissue init
+# → choose "Local directory"
+# → path: ../my-skill-registry   (relative to your project)
 ```
 
-- If `registry.json` is missing or does not list an id, the convention **`registry/<id>/`** is used.
+The local registry must be a **git repository** (so `HEAD` can be stored in the lockfile). No network auth needed.
 
-## Commands
+---
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    your project                       │
+│                                                       │
+│  .skill-issue/config.yaml  ──→  points to registry   │
+│  .skill-issue/lock.json    ──→  pinned commits       │
+│                                                       │
+│  .agents/skills/<id>/      ←──  installed skills      │
+│      ├── SKILL.md               (agents read these)   │
+│      └── hard/index.ts          (CI runs these)       │
+└───────────────────────┬──────────────────────────────┘
+                        │
+                        │  git clone / local path
+                        │
+┌───────────────────────▼──────────────────────────────┐
+│                skill registry repo                    │
+│                                                       │
+│  registry.json         maps skill-id → path           │
+│  registry/<id>/SKILL.md                               │
+│  registry/<id>/hard/   (optional executable checks)   │
+└──────────────────────────────────────────────────────┘
+```
+
+1. **`skissue init`** writes `.skill-issue/config.yaml` — either a GitHub `owner/repo` or a local path.
+2. **`skissue install <id>`** clones (or reads) the registry, resolves the skill path from `registry.json`, copies the skill tree into `.agents/skills/<id>/`, and writes a lockfile entry with the commit hash.
+3. **`skissue outdated`** compares locked commit hashes against the current registry HEAD.
+4. **`skissue update`** re-fetches and overwrites.
+
+---
+
+## Auth & Transport
+
+| Scenario                            | What happens                                |
+| ----------------------------------- | ------------------------------------------- |
+| `GITHUB_TOKEN` or `GH_TOKEN` is set | HTTPS with token (typical CI)               |
+| No token in env                     | SSH via `git@github.com:…` (typical laptop) |
+| `registry.useSsh: true`             | Force SSH                                   |
+| `registry.useSsh: false`            | Force HTTPS                                 |
+| Local registry                      | No auth needed                              |
+
+> Never put tokens in `config.yaml`. Use environment variables or a credential helper.
+
+---
+
+## CI & Automation
+
+Skills with `hard/index.ts` can be wired into your CI pipeline. The harness runner executes every hard skill that isn't marked with `hard/.no-auto-run`:
+
+```bash
+# In your CI workflow
+npx tsx .agents/skills/*/hard/index.ts
+```
+
+Or use the built-in harness runner if you've adopted the full skissue harness pattern:
+
+```bash
+npm run check:all
+```
+
+### Automated publishing (this repo)
 
-| Command                  | Description                                       |
-| ------------------------ | ------------------------------------------------- |
-| `skissue init`           | Create config interactively                       |
-| `skissue install <id>`   | Install skill at registry branch tip; update lock |
-| `skissue uninstall <id>` | Remove install dir and lock entry                 |
-| `skissue list`           | Show installed ids and lock metadata              |
-| `skissue manage`         | Interactive menu to install or uninstall skills   |
-| `skissue outdated`       | Compare locked commit vs current branch path diff |
-| `skissue update [id]`    | Re-install from registry                          |
-| `skissue doctor`         | Check Node, config, `git ls-remote`               |
+This repo uses a three-workflow CI/CD pipeline:
 
-`manage` is also available as `skissue browse`.
+1. **PR & push** — [`ci.yml`](.github/workflows/ci.yml) runs `npm run verify` (TypeScript, ESLint, Prettier, tests, harness, harness score, build)
+2. **Green main** — [`version-and-release.yml`](.github/workflows/version-and-release.yml) bumps the patch version, tags, and creates a GitHub Release
+3. **Tag push** — [`publish.yml`](.github/workflows/publish.yml) runs `npm publish --access public`
 
-### Interactive
+---
 
-After `init`, run `skissue manage` (or `browse`) to see registry skills vs installed skills and batch install or uninstall with prompts. Non-interactive `install` / `uninstall` remain for scripts.
+## Config Reference
+
+`.skill-issue/config.yaml`:
+
+```yaml
+# GitHub registry
+registry:
+  owner: midyan
+  repo: skill-registry
+  branch: main
+  # useSsh: true | false | omit for auto-detection
+skillsRoot: .agents/skills
+
+# — OR —
+
+# Local registry
+registry:
+  path: ../skill-registry   # relative to project root
+  branch: main
+skillsRoot: .agents/skills
+```
+
+`.skill-issue/lock.json` is managed by the CLI. Commit it — it pins your skill versions.
+
+---
+
+## Requirements
+
+- **Node** 24+ (see `.nvmrc`)
+- **git** on your `PATH`
+- For **remote** registries: `GITHUB_TOKEN` / `GH_TOKEN`, or SSH keys / `gh auth`
+- For **local** registries: just a git checkout on disk
+
+---
 
 ## Development
 
 ```bash
-npm install   # installs deps and runs `prepare` — enables Husky git hooks
-npm run verify
+git clone https://github.com/midyan/skill-issue.git
+cd skill-issue
+npm install          # also enables Husky git hooks via prepare
+npm run verify       # typecheck + lint + format + test + harness + harness score + build
 ```
 
-**`npm run verify`** runs TypeScript (`tsc --noEmit`), ESLint, Prettier check, Vitest, **`npm run check:all`** ( **`harness/runner.ts`** — each **`harness/<id>/hard/index.ts`** without **`hard/.no-auto-run`** ), then **`npm run build`**. The same pipeline runs on **`git commit`** via **`.husky/pre-commit`** (skip with **`git commit --no-verify`** if needed). See [harness/SKILL.md](harness/SKILL.md), [harness/repo-verify/SKILL.md](harness/repo-verify/SKILL.md), and [docs/HARNESS.md](docs/HARNESS.md).
+| Script                  | What it does                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------- |
+| `npm run dev -- <args>` | Run CLI from source via tsx                                                   |
+| `npm run verify`        | Full pipeline: tsc, eslint, prettier, vitest, check:all, harness score, build |
+| `npm run build`         | Production build via esbuild                                                  |
+| `npm test`              | Run vitest                                                                    |
+| `npm run check:all`     | Harness runner (hard skill checks)                                            |
+| `npm run repo-verify`   | Same as verify, with explicit skill discovery output                          |
+
+### Project structure
+
+```
+src/
+├── entry.ts            ← CLI bootstrap (commander)
+├── config.ts           ← config loading & validation
+├── lockfile.ts         ← lock.json I/O
+├── paths.ts            ← path resolution
+├── io.ts               ← filesystem copy helpers
+├── commands/           ← subcommands (init, install, manage, ...)
+│   └── banner.ts       ← the beautiful TUI banner
+├── git/                ← git invocation & registry checkout
+└── registry/           ← skill resolution from checkout
+```
+
+---
+
+## Contributing
+
+1. Fork it
+2. Create your branch (`git checkout -b feat/amazing-thing`)
+3. Make your changes
+4. Run `npm run verify` — everything must pass
+5. Commit with [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, ...)
+6. Open a PR
+
+---
+
+## License
+
+[MIT](LICENSE) — go wild.
+
+---
+
+<p align="center">
+  <sub>Built with obsessive attention to developer experience.</sub><br>
+  <sub>If your agents have a skill issue, now there's a fix for that.</sub>
+</p>
+
+<p align="center">
+  <sub>
+    <pre>
+    ╭────────────────────────────────╮
+    │                                │
+    │   no more skill issues. ever.  │
+    │                                │
+    ╰────────────────────────────────╯
+    </pre>
+  </sub>
+</p>

package/dist/entry.js

@@ -4,7 +4,7 @@
 // src/entry.ts
 import { Command } from "commander";
 import { createRequire } from "node:module";
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 
 // src/commands/init.ts
 import * as p from "@clack/prompts";
@@ -126,7 +126,7 @@ import { join as join2, resolve } from "node:path";
 // src/git/exec.ts
 import { spawn } from "node:child_process";
 function execGit(args, options = {}) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const env = { ...process.env, ...options.env };
     if (env.GIT_TERMINAL_PROMPT === void 0) {
       env.GIT_TERMINAL_PROMPT = "0";
@@ -151,7 +151,7 @@ function execGit(args, options = {}) {
     child.on("close", (code, signal) => {
       if (timeout !== void 0) clearTimeout(timeout);
       if (signal === "SIGTERM") {
-        resolve3({
+        resolve4({
           code: 124,
           stdout,
           stderr: `${stderr}
@@ -159,11 +159,11 @@ skissue: git timed out after ${timeoutMs}ms`.trim()
         });
         return;
       }
-      resolve3({ code: code ?? 1, stdout, stderr });
+      resolve4({ code: code ?? 1, stdout, stderr });
     });
     child.on("error", (err) => {
       if (timeout !== void 0) clearTimeout(timeout);
-      resolve3({ code: 1, stdout, stderr: String(err) });
+      resolve4({ code: 1, stdout, stderr: String(err) });
     });
   });
 }
@@ -330,8 +330,8 @@ async function ensureCommit(repoPath, sha) {
 async function diffPath(repoPath, fromCommit, toCommit, pathInRepo) {
   await ensureCommit(repoPath, fromCommit);
   await ensureCommit(repoPath, toCommit);
-  const p3 = pathInRepo.replace(/^\.\/+/, "").replace(/\/+$/, "");
-  const diff = await execGit(["diff", fromCommit, toCommit, "--", p3], { cwd: repoPath });
+  const p4 = pathInRepo.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  const diff = await execGit(["diff", fromCommit, toCommit, "--", p4], { cwd: repoPath });
   if (diff.code !== 0) {
     throw new Error(`git diff failed: ${diff.stderr}`);
   }
@@ -470,11 +470,11 @@ async function runInit(cwd) {
     process.exit(0);
   }
   cfg = ConfigSchema.parse({ ...cfg, skillsRoot: String(skillsRoot).trim() });
-  const confirm3 = await p.confirm({
+  const confirm4 = await p.confirm({
     message: hasExistingConfig ? `Overwrite ${chalk.cyan(".skill-issue/config.yaml")} and use ${chalk.cyan(cfg.skillsRoot)} for installs?` : `Create ${chalk.cyan(".skill-issue/config.yaml")} and use ${chalk.cyan(cfg.skillsRoot)} for installs?`,
     initialValue: true
   });
-  if (p.isCancel(confirm3) || !confirm3) {
+  if (p.isCancel(confirm4) || !confirm4) {
     p.cancel("Aborted.");
     process.exit(0);
   }
@@ -567,8 +567,8 @@ async function resolveSkillPath(registryRepoRoot, skillId) {
   }
   return { skillPath: join3("registry", skillId).replace(/\\/g, "/"), source: "convention" };
 }
-function normalizeRelPath(p3) {
-  return p3.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+function normalizeRelPath(p4) {
+  return p4.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
 }
 
 // src/io.ts
@@ -576,9 +576,9 @@ import { access as access2, cp, rm as rm2 } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join as join4 } from "node:path";
 async function assertSkillMdPresent(skillSourceDir) {
-  const p3 = join4(skillSourceDir, "SKILL.md");
+  const p4 = join4(skillSourceDir, "SKILL.md");
   try {
-    await access2(p3, constants.R_OK);
+    await access2(p4, constants.R_OK);
   } catch {
     throw new Error(`Expected SKILL.md in skill path: ${skillSourceDir}`);
   }
@@ -1043,11 +1043,167 @@ async function runDoctor(cwd) {
   }
 }
 
+// src/commands/init-registry.ts
+import * as p3 from "@clack/prompts";
+import chalk10 from "chalk";
+import { existsSync as existsSync4, statSync as statSync2 } from "node:fs";
+import { mkdir as mkdir5, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join7, resolve as resolve2 } from "node:path";
+function validateSkillId(raw) {
+  const id = raw.trim();
+  if (!id) return "Skill id is required";
+  if (id.includes("/") || id.includes("\\")) return "Use a single segment (no path separators)";
+  if (id === "." || id === ".." || id.includes("..")) return "Invalid skill id";
+  return void 0;
+}
+function registryLayoutExists(root) {
+  const jsonPath = join7(root, "registry.json");
+  const regDir = join7(root, "registry");
+  if (existsSync4(jsonPath)) return true;
+  if (!existsSync4(regDir)) return false;
+  try {
+    return statSync2(regDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function skillMarkdown(skillId) {
+  const title = skillId.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  return `---
+name: ${skillId}
+description: Sample skill scaffolded by skissue init-registry. Replace this description.
+---
+
+# ${title}
+
+A minimal starter skill for your registry.
+
+## When to use
+
+Use when the user works with this sample capability (customize this section).
+
+## Instructions
+
+1. Edit this file to describe what the agent should do.
+2. Optionally add \`hard/\` with executable checks.
+`;
+}
+async function scaffoldMinimalRegistry(params) {
+  const { root, skillId, runGitInit } = params;
+  const regPath = `registry/${skillId}`;
+  const manifest = { skills: { [skillId]: regPath } };
+  await mkdir5(join7(root, regPath), { recursive: true });
+  await writeFile3(join7(root, "registry.json"), `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  await writeFile3(join7(root, regPath, "SKILL.md"), skillMarkdown(skillId), "utf8");
+  let gitInitRan = false;
+  if (runGitInit) {
+    const r = await execGit(["init"], { cwd: root });
+    if (r.code === 0) {
+      gitInitRan = true;
+    } else {
+      throw new Error(`git init failed: ${r.stderr || r.stdout || `exit ${r.code}`}`);
+    }
+  }
+  return { root, skillId, gitInitRan };
+}
+async function runInitRegistry(cwd) {
+  p3.intro(chalk10.bold("skissue init-registry"));
+  const where = await p3.select({
+    message: "Where should the skill registry live?",
+    options: [
+      { value: "here", label: "Current directory \u2014 create registry files here" },
+      { value: "other", label: "Another directory \u2014 I will enter the path" }
+    ],
+    initialValue: "here"
+  });
+  if (p3.isCancel(where)) {
+    p3.cancel("Aborted.");
+    process.exit(0);
+  }
+  let root;
+  if (where === "here") {
+    root = resolve2(cwd);
+  } else {
+    const raw = await p3.text({
+      message: "Path to registry root (absolute or relative to current directory)",
+      placeholder: "../my-skill-registry",
+      validate: (v) => v?.trim() ? void 0 : "Required"
+    });
+    if (p3.isCancel(raw)) {
+      p3.cancel("Aborted.");
+      process.exit(0);
+    }
+    root = resolve2(cwd, String(raw).trim());
+  }
+  const exists = registryLayoutExists(root);
+  if (exists) {
+    const ok = await p3.confirm({
+      message: `${chalk10.yellow("registry.json and/or registry/ already exist here.")} Replace with a minimal single-skill layout?`,
+      initialValue: false
+    });
+    if (p3.isCancel(ok) || !ok) {
+      p3.cancel("Aborted. No files were changed.");
+      process.exit(0);
+    }
+  }
+  const idRaw = await p3.text({
+    message: "Sample skill id (folder name under registry/)",
+    initialValue: "sample-skill",
+    validate: (v) => validateSkillId(String(v ?? ""))
+  });
+  if (p3.isCancel(idRaw)) {
+    p3.cancel("Aborted.");
+    process.exit(0);
+  }
+  const skillId = String(idRaw).trim();
+  const gitDir = join7(root, ".git");
+  const hadGit = existsSync4(gitDir);
+  let runGitInit = false;
+  if (!hadGit) {
+    const initGit = await p3.confirm({
+      message: "No git repository here yet. Run `git init`? (recommended \u2014 skissue local registry mode needs a git repo)",
+      initialValue: true
+    });
+    if (p3.isCancel(initGit)) {
+      p3.cancel("Aborted.");
+      process.exit(0);
+    }
+    runGitInit = Boolean(initGit);
+  }
+  try {
+    const result = await scaffoldMinimalRegistry({ root, skillId, runGitInit });
+    if (!hadGit && !result.gitInitRan) {
+      p3.note(
+        "This folder is not a git repository. Run `git init` before using it as a local skissue registry.",
+        chalk10.yellow("Heads up")
+      );
+    }
+    p3.outro(
+      chalk10.green(
+        `Wrote ${chalk10.cyan("registry.json")} and ${chalk10.cyan(`registry/${skillId}/SKILL.md`)} under ${chalk10.cyan(result.root)}`
+      )
+    );
+  } catch (e) {
+    p3.cancel(e instanceof Error ? e.message : String(e));
+    process.exitCode = 1;
+  }
+}
+
 // src/entry.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
 var program = new Command();
 program.name("skissue").description("Install and sync agent skills from a GitHub registry or a local registry path").version(pkg.version);
+program.command("init-registry").description("Scaffold a minimal git-backed skill registry (registry.json + sample skill)").action(async () => {
+  const cwd = process.cwd();
+  try {
+    await runInitRegistry(cwd);
+  } catch (e) {
+    console.error(e);
+    process.exitCode = 1;
+  }
+});
 program.command("init").description("Create .skill-issue/config and confirm skills install path").action(async () => {
   const cwd = process.cwd();
   try {
@@ -1106,7 +1262,7 @@ program.command("update").description("Re-fetch and overwrite installed skill(s)
   }
 });
 program.command("doctor").description("Check Node, config, and sync registry checkout").option("-C, --cwd <path>", "Project root", process.cwd()).action(async (opts) => {
-  const cwd = resolve2(opts.cwd ?? process.cwd());
+  const cwd = resolve3(opts.cwd ?? process.cwd());
   try {
     await runDoctor(cwd);
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skissue",
-  "version": "0.1.11",
+  "version": "0.1.16",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
     "check:registry": "tsx harness/validate-registry/hard/index.ts",
     "check:all": "tsx harness/runner.ts",
     "check:harness-score": "tsx harness/report-harness-score/hard/index.ts",
-    "verify": "tsc --noEmit && npm run lint && npm run format:check && npm test && npm run check:all && npm run build",
+    "verify": "tsc --noEmit && npm run lint && npm run format:check && npm test && npm run check:all && npm run check:harness-score && npm run build",
     "repo-verify": "tsx harness/repo-verify/hard/index.ts",
     "prepublishOnly": "npm run build",
     "prepare": "husky || node -e \"process.exit(0)\""