super-skill-cli 0.9.2__tar.gz

super_skill_cli-0.9.2/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "super-skill",
+  "owner": {
+    "name": "sdsrss",
+    "email": "sammuaicode@gmail.com"
+  },
+  "metadata": {
+    "description": "super-skill: personal Agent-Skill package manager (versioned registry, rollback, mining).",
+    "version": "0.9.2"
+  },
+  "plugins": [
+    {
+      "name": "super-skill",
+      "source": "./",
+      "description": "Git-backed versioned registry for your Claude Code skills: seed import, explain/provenance, one-command rollback, integrity doctor, and opportunity mining. Wraps the `super-skill` CLI (pip/uv installable as super-skill-cli).",
+      "version": "0.9.2",
+      "category": "development"
+    }
+  ]
+}

super_skill_cli-0.9.2/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "super-skill",
+  "version": "0.9.2",
+  "description": "Personal Agent-Skill package manager: a git-backed, versioned registry for your Claude Code skills with seed import, provenance/explain, one-command rollback, integrity doctor, and opportunity mining from captured sessions.",
+  "author": {
+    "name": "sdsrss",
+    "url": "https://github.com/sdsrss"
+  },
+  "repository": "https://github.com/sdsrss/super-skill",
+  "license": "MIT",
+  "keywords": ["claude-code", "agent-skills", "skill-manager", "registry", "package-manager"]
+}

super_skill_cli-0.9.2/.gitignore

@@ -0,0 +1,45 @@
+# Project-local docs & AI assistant config (not committed)
+docs/
+CLAUDE.md
+.claude/
+.code-graph/
+tasks/
+MEMORY.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.python-version
+.uv-cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environment & secrets
+.env
+.env.*
+*.local
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node (tooling, if any)
+node_modules/
+
+# Logs & temp
+*.log
+tmp/

super_skill_cli-0.9.2/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic versioning.
+
+## [0.9.2] - 2026-07-12
+
+### Changed
+- **README rewritten and aligned to shipped features** — bilingual (English
+  default + `README.zh-CN.md`), with install (Claude Code plugin / CLI / Codex),
+  a feature table, a differentiation comparison, usage, configuration, an honest
+  scope note, and an FAQ. Corrected the write-path description: the host skills
+  directory is written by `approve` / `rollback` / `doctor --fix` (`seed` is
+  read-only on the host). Added a GitHub repo description and topics.
+
+## [0.9.1] - 2026-07-12
+
+### Fixed
+- **`codex/install.sh` now ships executable** — it was committed with mode 100644,
+  so a fresh clone could only run it as `bash codex/install.sh`, not `./codex/install.sh`
+  as the README shows. Set the git exec bit (100755). The guard test now checks the
+  git-tracked mode (`git ls-files --stage`) instead of the working-tree mode, which
+  some filesystems report as executable regardless.
+
+## [0.9.0] - 2026-07-12
+
+### Added
+- **Codex install package** (`codex/`) — Codex has no marketplace; it reads
+  open-standard `SKILL.md` from `~/.agents/skills`. Ships a portable `super-skill`
+  meta-skill (name+description only, no Claude-specific slash commands) plus an
+  idempotent `codex/install.sh` that drops it into `~/.agents/skills/super-skill/`,
+  and `codex/README.md`. The CLI is host-agnostic — Codex users `pipx install
+  super-skill-cli` the same way and point it at the Codex dir with
+  `SUPER_SKILL_HOST_SKILLS=~/.agents/skills`.
+
+### Notes
+- No `agents/openai.yaml` is shipped — that Codex host-extension's exact schema is
+  Codex-version-specific; the package ships only the open-standard SKILL.md every
+  Codex version reads. A Codex Target Adapter inside the CLI (docs/01 FR-PUB-2)
+  remains P1. PyPI publish is still a separate credentialed step.
+
+## [0.8.0] - 2026-07-12
+
+### Added
+- **Claude Code plugin** — install via `/plugin marketplace add sdsrss/super-skill`
+  then `/plugin install super-skill`. Ships slash commands (`/super-skill:status`,
+  `:mine`, `:doctor`, `:candidates`, `:seed`), a `super-skill` meta-skill Claude
+  invokes when you ask to version/explain/roll back a skill, and `hooks/hooks.json`
+  wiring the six host events to `super-skill capture`. If your Claude Code build
+  doesn't auto-load plugin hooks, `super-skill hooks-config` remains the reliable
+  manual path.
+- **PyPI-installable CLI** — packaging metadata (MIT license, classifiers, URLs)
+  so the CLI installs with `uv tool install super-skill-cli` / `pipx install
+  super-skill-cli`. The command stays `super-skill`.
+
+### Changed
+- **Distribution renamed to `super-skill-cli`** on PyPI — the bare `super-skill`
+  name is held by an unrelated package. No action needed for anyone: prior
+  releases were git tags only, never published to a package registry. The
+  installed command name is unchanged (`super-skill`).
+
+### Notes
+- Codex plugin packaging stays a deferred P1 (per docs/01 FR-PUB-2). PyPI publish
+  is a separate credentialed step, not performed by this release.
+
+## [0.7.0] - 2026-07-12
+
+### Added
+- **Mine reminder** — `status` now nudges (`reminder : N distinct sessions
+  unmined — run mine`) once enough new sessions have accumulated since the last
+  mine. A watermark (`mine_state.json`) records the distinct-session count at the
+  last mine, so "unmined" is honest: it clears when you mine and only fires again
+  as new sessions pile up. Threshold defaults to 3 (`SUPER_SKILL_MINE_REMINDER`
+  overrides). `mine` also reports the distinct-session count when nothing yet
+  clears the recurrence threshold, and both `mine` and `candidate draft` reset
+  the watermark.
+
+## [0.6.0] - 2026-07-12
+
+### Added
+- **Candidate visibility** — `status` now reports a candidate count with a
+  per-status breakdown, and `list` appends a "pending candidates" section so
+  drafts awaiting approval are visible without a separate command.
+
+## [0.5.0] - 2026-07-12
+
+### Added
+- **`doctor --fix`** — mechanical repair. Restores tampered/missing versions from
+  git HEAD (the committed, correct content) and re-materializes host drift, then
+  **re-verifies**: the exit status reflects what remains after the fix, not what
+  was attempted. Issues needing judgment (a dangling active pointer, a name
+  mismatch) are reported for manual resolution rather than auto-changed.
+
+## [0.4.0] - 2026-07-12
+
+Hardens the v1 package manager.
+
+### Added
+- **`doctor`** — read-only registry integrity check. Re-hashes every stored
+  version against the `artifact_hash` recorded at promotion (catching tampering,
+  corruption, or a hand-edit that bypassed the registry), checks the active
+  pointer resolves, and reports host drift. Exits 1 on an integrity error;
+  remediation (`rollback` / `seed` / re-approve) is left to the user.
+
+## [0.3.0] - 2026-07-12
+
+Closes out the walking skeleton: `candidate approve` now runs two hard gates
+before it writes anything, and real sessions can be wired into capture.
+
+### Added
+- **Instruction-layer adversarial gate** (docs/04 §2.4bis) — v1's only mandatory
+  security gate. Rule-scans a candidate's body + description for external-action
+  imperatives (`curl|bash`, network fetch, credential access, `ignore previous`
+  overrides, run-undeclared-script) and blocks `approve` before any write. v1
+  candidates are pure text the host Agent runs as trusted instructions, so a
+  poisoned imperative is the code×instruction seam single-tool scanners miss.
+- **Deterministic eval-lite hard gate** (docs/04 §1.6) — schema, zero
+  credential/PII leak, and the agentskills token budget, checked before promote.
+  The No Skill / Skill two-arm is labelled *Insufficient Evidence* at personal
+  scale (no corpus/harness) rather than faked.
+- **`hooks-config`** — prints the `settings.json` hooks block wiring the six host
+  events to `super-skill capture`, so real sessions accumulate into the WAL.
+  Print-only; you merge it into `~/.claude/settings.json` yourself.
+
+## [0.2.0] - 2026-07-12
+
+Completes the walking-skeleton loop: mined opportunity families can now become
+human-approved skills, still routed through candidate → gate → promote (no
+component writes the production skill set except on approve).
+
+### Added
+- **Candidate approval loop** — `candidate draft` scaffolds a skill from a mined
+  family (an honest TODO-stub; coarse mining can name a recurring family, not
+  author its procedure), `candidate list/show` review it, and `candidate approve`
+  promotes the (human-editable) draft: registers an immutable ACTIVE version and
+  materializes it to the host skills dir. Drafts live as pre-promotion scratch,
+  git-ignored by the registry — only `approve` writes tracked state (One Writer
+  Rule). `candidate reject` records a decision without promoting.
+
+### Fixed
+- **Mining noise** — coarse mining no longer treats the hook envelope as content:
+  the event type is no longer seeded into the token stream, envelope keys
+  (`hook_event_name` / `session_id` / `cwd` / …) are skipped, and `[REDACTED:kind]`
+  placeholders are stripped. These had produced junk families (`userpromptsubmit-*`,
+  cwd-derived slugs, redaction kind names).
+
+## [0.1.0] - 2026-07-12
+
+First release: the **M0+WS package-manager** scope. A GATE-1 measurement of the
+author's own history showed the candidate opportunity flow does not yet clear the
+threshold that would justify the self-learning loop (M2–M5), so v1 is deliberately
+the package manager, not the factory.
+
+### Added
+- **Git-backed registry** — per-skill `meta.json` (Skill pointer + SkillVersion DAG
+  + audit trail); git provides integrity, audit and rollback.
+- **Seed import** — bring existing `~/.claude/skills` under version control,
+  read-only on the host, idempotent by content hash.
+- **CLI** — `seed`, `status`, `list`, `show`, `explain`, `rollback`.
+- **WS capture pipeline** — append-only JSONL event WAL with regex redaction that
+  runs before any write (secret values never reach disk; only kind + field location
+  are recorded), plus coarse opportunity mining that surfaces task families
+  recurring across ≥3 sessions. Exposed via `capture` (host hook, never fails the
+  session) and `mine`.
+- Strict typing (mypy) and lint (ruff) across the package; 41 tests.
+
+### Notes
+- Deferred to a research track: candidate generation/approval loop, optimization,
+  external distillation, dynamic sandbox, signed Publisher, and the runtime Router
+  (milestones M1–M5). Not published to any package registry.

super_skill_cli-0.9.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sdsrss
+
+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.

super_skill_cli-0.9.2/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: super-skill-cli
+Version: 0.9.2
+Summary: Personal Agent-Skill package manager: versioned registry, seed import, explain, rollback (M0+WS scope).
+Project-URL: Homepage, https://github.com/sdsrss/super-skill
+Project-URL: Repository, https://github.com/sdsrss/super-skill
+Author-email: sdsrss <sammuaicode@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,claude-code,package-manager,registry,skill-manager
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<!-- SEO: Claude Code Agent Skills package manager — version control, rollback, provenance, integrity checks for ~/.claude/skills and ~/.agents/skills (Codex). -->
+
+# super-skill
+
+**Version control, rollback, and provenance for your Claude Code and Codex Agent Skills.**
+super-skill is a git-backed package manager for the skills in `~/.claude/skills`
+(and Codex's `~/.agents/skills`): it puts every skill under version history,
+tells you where each one came from, rolls any skill back with one command, and
+checks the registry for tampering — with secret-redacted session capture and
+safety-gated promotion built in.
+
+**English** · [简体中文](README.zh-CN.md)
+
+---
+
+## Why super-skill
+
+Agent Skills are just Markdown files in a directory. That directory has no
+history: edit a `SKILL.md` and the previous version is gone; you can't tell which
+skill came from where, why it's there, or whether one was quietly changed. There
+is no undo.
+
+super-skill treats your skills like packages: **versioned, auditable, reversible.**
+
+## Highlights
+
+- **One-command rollback** — a skill regressed? `super-skill rollback <id>` switches
+  the active version and re-materializes it to your skills directory.
+- **Provenance & audit** — `super-skill explain <id>` answers *why does this skill
+  exist, where did it come from, how do I undo it* from an immutable audit trail.
+- **Tamper detection** — `super-skill doctor` re-hashes every stored version against
+  the hash recorded at promotion; `--fix` restores git-recoverable versions.
+- **Redaction before disk** — session capture strips secrets and private paths
+  *before* anything is written; secret values never reach the log.
+- **Safety-gated promotion** — a candidate becomes a skill only through two hard
+  gates (an instruction-layer adversarial scan + a deterministic eval-lite).
+- **Runs where your agent runs** — a Claude Code plugin, a Codex install package,
+  and a host-agnostic CLI, all driven by the same `super-skill` command.
+
+## Install
+
+### Claude Code (plugin)
+
+```
+/plugin marketplace add sdsrss/super-skill
+/plugin install super-skill
+```
+
+Adds slash commands (`/super-skill:status`, `:mine`, `:doctor`, `:candidates`,
+`:seed`), a `super-skill` skill Claude invokes when you ask to version, explain,
+or roll back a skill, and capture hooks. The plugin drives the CLI, so install
+that too:
+
+### CLI
+
+```bash
+uv tool install super-skill-cli      # or: pipx install super-skill-cli
+super-skill status                   # the command is `super-skill`
+```
+
+The PyPI distribution is **`super-skill-cli`** (the bare `super-skill` name
+belongs to an unrelated package); the installed command is `super-skill`.
+One-shot, no install: `uvx --from super-skill-cli super-skill status`.
+
+### Codex
+
+Codex reads open-standard `SKILL.md` from `~/.agents/skills` — no marketplace
+needed:
+
+```bash
+pipx install super-skill-cli
+codex/install.sh                     # drops the meta-skill into ~/.agents/skills
+```
+
+Point the CLI at the Codex directory with `SUPER_SKILL_HOST_SKILLS=~/.agents/skills`.
+See [`codex/README.md`](codex/README.md).
+
+## Features
+
+| Command | What it does |
+|---|---|
+| `seed` | Import existing `~/.claude/skills` under version control — read-only on the host, idempotent by content hash. |
+| `status` / `list` | Registry summary (skills, versions, events, candidates) and the skill list. |
+| `show <id>` | Frontmatter, version history, and content hashes for one skill. |
+| `explain <id>` | Provenance chain + audit trail + the exact rollback command. |
+| `rollback <id> [--to vN]` | Switch the active version and re-materialize it to the host. |
+| `doctor` / `doctor --fix` | Integrity check (hashes, active pointer, host sync); `--fix` restores git-recoverable versions and re-materializes drift, then re-verifies. |
+| `capture` | Append a host event to the redacted WAL — reads hook JSON on stdin, never fails the session. |
+| `mine` | Surface task families recurring across ≥3 distinct sessions; nudges you once enough new sessions accumulate. |
+| `candidate draft/show/approve/reject` | Turn a mined family into a skill: draft → review → two hard gates → promote & materialize. |
+| `hooks-config` | Print the `settings.json` hooks block that wires session capture. |
+
+State lives in `~/.super-skill/` — a real git repository, so **audit and rollback
+are git.**
+
+## How it's different
+
+|  | Plain `~/.claude/skills` | super-skill |
+|---|:---:|:---:|
+| Version history per skill | ✗ | ✓ (git-backed DAG) |
+| One-command rollback | ✗ | ✓ |
+| Provenance / "why is this here" | ✗ | ✓ |
+| Tamper / drift detection | ✗ | ✓ (`doctor`) |
+| Secret redaction on capture | ✗ | ✓ (before disk) |
+| Safety-gated promotion | ✗ | ✓ (two hard gates) |
+| Claude Code **and** Codex | manual | ✓ one CLI |
+
+super-skill is a **package manager, not a skill generator**: it manages, versions,
+and audits the skills you already have or approve — it does not write skills for
+you or change their behavior behind your back. Every write path is explicit and
+reversible; your skills directory is only ever written on `approve`, `rollback`,
+or `doctor --fix` (`seed` reads it but never modifies it).
+
+## Usage
+
+```bash
+# Bring your current skills under version control
+super-skill seed
+super-skill status
+
+# See where a skill came from and how to undo it
+super-skill explain my-skill
+
+# Undo a bad change
+super-skill rollback my-skill
+
+# Check nothing was tampered with; repair recoverable drift
+super-skill doctor
+super-skill doctor --fix
+
+# Turn recurring work into a skill (capture must be wired first — see hooks-config)
+super-skill mine
+super-skill candidate draft
+super-skill candidate show <id>      # edit the draft, then:
+super-skill candidate approve <id>
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `SUPER_SKILL_HOME` | `~/.super-skill` | Registry + control state (a git repo). |
+| `SUPER_SKILL_HOST_SKILLS` | `~/.claude/skills` | Skills directory to seed/materialize (set to `~/.agents/skills` for Codex). |
+| `SUPER_SKILL_MINE_REMINDER` | `3` | Distinct unmined sessions before `status` nudges you to mine. |
+
+## Scope
+
+super-skill is deliberately the **package-manager** form (milestones M0 + WS). The
+self-learning loop — automatically optimizing, distilling, and promoting skills
+(milestones M1–M5) — is a **deferred research track**: a measurement of real usage
+did not clear the threshold that would justify building it, so v1 is frozen as a
+package manager with audit and rollback. It does not self-evolve your skills, and
+this README does not imply it does.
+
+## FAQ
+
+**Does super-skill run or change my skills' behavior?**
+No. It manages the files (version, audit, rollback, integrity) and never edits a
+skill's content on its own. Approving a candidate promotes a draft *you* reviewed.
+
+**Will it touch `~/.claude/skills` without asking?**
+Three commands write there — `approve` (promote a reviewed candidate), `rollback`,
+and `doctor --fix`. `seed` reads your skills into the registry but never modifies
+them; `status`/`list`/`show`/`explain`/`doctor` are read-only.
+
+**Are my secrets safe in captured sessions?**
+Redaction runs *before* any write: secret values and private paths never reach the
+log. Capture is off until you wire it (`super-skill hooks-config`).
+
+**Do I need PyPI for the plugin to work?**
+The plugin calls the `super-skill` CLI on your PATH. Until the PyPI release,
+install the CLI from source: `uv tool install git+https://github.com/sdsrss/super-skill`.
+
+**Does it support Codex?**
+Yes — the same CLI plus a `codex/` install package for `~/.agents/skills`. A Codex
+*Target Adapter inside the CLI* is a later item; distributing skills to Codex needs
+no extra step since they already live in `~/.agents/skills`.
+
+## Develop
+
+Uses [uv](https://docs.astral.sh/uv/). Python 3.12.
+
+```bash
+uv sync                       # venv + deps
+uv run pytest                 # tests
+uv run ruff check .           # lint
+uv run mypy super_skill/      # typecheck
+```
+
+## License
+
+[MIT](LICENSE) © sdsrss

super_skill_cli-0.9.2/README.md

@@ -0,0 +1,192 @@
+<!-- SEO: Claude Code Agent Skills package manager — version control, rollback, provenance, integrity checks for ~/.claude/skills and ~/.agents/skills (Codex). -->
+
+# super-skill
+
+**Version control, rollback, and provenance for your Claude Code and Codex Agent Skills.**
+super-skill is a git-backed package manager for the skills in `~/.claude/skills`
+(and Codex's `~/.agents/skills`): it puts every skill under version history,
+tells you where each one came from, rolls any skill back with one command, and
+checks the registry for tampering — with secret-redacted session capture and
+safety-gated promotion built in.
+
+**English** · [简体中文](README.zh-CN.md)
+
+---
+
+## Why super-skill
+
+Agent Skills are just Markdown files in a directory. That directory has no
+history: edit a `SKILL.md` and the previous version is gone; you can't tell which
+skill came from where, why it's there, or whether one was quietly changed. There
+is no undo.
+
+super-skill treats your skills like packages: **versioned, auditable, reversible.**
+
+## Highlights
+
+- **One-command rollback** — a skill regressed? `super-skill rollback <id>` switches
+  the active version and re-materializes it to your skills directory.
+- **Provenance & audit** — `super-skill explain <id>` answers *why does this skill
+  exist, where did it come from, how do I undo it* from an immutable audit trail.
+- **Tamper detection** — `super-skill doctor` re-hashes every stored version against
+  the hash recorded at promotion; `--fix` restores git-recoverable versions.
+- **Redaction before disk** — session capture strips secrets and private paths
+  *before* anything is written; secret values never reach the log.
+- **Safety-gated promotion** — a candidate becomes a skill only through two hard
+  gates (an instruction-layer adversarial scan + a deterministic eval-lite).
+- **Runs where your agent runs** — a Claude Code plugin, a Codex install package,
+  and a host-agnostic CLI, all driven by the same `super-skill` command.
+
+## Install
+
+### Claude Code (plugin)
+
+```
+/plugin marketplace add sdsrss/super-skill
+/plugin install super-skill
+```
+
+Adds slash commands (`/super-skill:status`, `:mine`, `:doctor`, `:candidates`,
+`:seed`), a `super-skill` skill Claude invokes when you ask to version, explain,
+or roll back a skill, and capture hooks. The plugin drives the CLI, so install
+that too:
+
+### CLI
+
+```bash
+uv tool install super-skill-cli      # or: pipx install super-skill-cli
+super-skill status                   # the command is `super-skill`
+```
+
+The PyPI distribution is **`super-skill-cli`** (the bare `super-skill` name
+belongs to an unrelated package); the installed command is `super-skill`.
+One-shot, no install: `uvx --from super-skill-cli super-skill status`.
+
+### Codex
+
+Codex reads open-standard `SKILL.md` from `~/.agents/skills` — no marketplace
+needed:
+
+```bash
+pipx install super-skill-cli
+codex/install.sh                     # drops the meta-skill into ~/.agents/skills
+```
+
+Point the CLI at the Codex directory with `SUPER_SKILL_HOST_SKILLS=~/.agents/skills`.
+See [`codex/README.md`](codex/README.md).
+
+## Features
+
+| Command | What it does |
+|---|---|
+| `seed` | Import existing `~/.claude/skills` under version control — read-only on the host, idempotent by content hash. |
+| `status` / `list` | Registry summary (skills, versions, events, candidates) and the skill list. |
+| `show <id>` | Frontmatter, version history, and content hashes for one skill. |
+| `explain <id>` | Provenance chain + audit trail + the exact rollback command. |
+| `rollback <id> [--to vN]` | Switch the active version and re-materialize it to the host. |
+| `doctor` / `doctor --fix` | Integrity check (hashes, active pointer, host sync); `--fix` restores git-recoverable versions and re-materializes drift, then re-verifies. |
+| `capture` | Append a host event to the redacted WAL — reads hook JSON on stdin, never fails the session. |
+| `mine` | Surface task families recurring across ≥3 distinct sessions; nudges you once enough new sessions accumulate. |
+| `candidate draft/show/approve/reject` | Turn a mined family into a skill: draft → review → two hard gates → promote & materialize. |
+| `hooks-config` | Print the `settings.json` hooks block that wires session capture. |
+
+State lives in `~/.super-skill/` — a real git repository, so **audit and rollback
+are git.**
+
+## How it's different
+
+|  | Plain `~/.claude/skills` | super-skill |
+|---|:---:|:---:|
+| Version history per skill | ✗ | ✓ (git-backed DAG) |
+| One-command rollback | ✗ | ✓ |
+| Provenance / "why is this here" | ✗ | ✓ |
+| Tamper / drift detection | ✗ | ✓ (`doctor`) |
+| Secret redaction on capture | ✗ | ✓ (before disk) |
+| Safety-gated promotion | ✗ | ✓ (two hard gates) |
+| Claude Code **and** Codex | manual | ✓ one CLI |
+
+super-skill is a **package manager, not a skill generator**: it manages, versions,
+and audits the skills you already have or approve — it does not write skills for
+you or change their behavior behind your back. Every write path is explicit and
+reversible; your skills directory is only ever written on `approve`, `rollback`,
+or `doctor --fix` (`seed` reads it but never modifies it).
+
+## Usage
+
+```bash
+# Bring your current skills under version control
+super-skill seed
+super-skill status
+
+# See where a skill came from and how to undo it
+super-skill explain my-skill
+
+# Undo a bad change
+super-skill rollback my-skill
+
+# Check nothing was tampered with; repair recoverable drift
+super-skill doctor
+super-skill doctor --fix
+
+# Turn recurring work into a skill (capture must be wired first — see hooks-config)
+super-skill mine
+super-skill candidate draft
+super-skill candidate show <id>      # edit the draft, then:
+super-skill candidate approve <id>
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `SUPER_SKILL_HOME` | `~/.super-skill` | Registry + control state (a git repo). |
+| `SUPER_SKILL_HOST_SKILLS` | `~/.claude/skills` | Skills directory to seed/materialize (set to `~/.agents/skills` for Codex). |
+| `SUPER_SKILL_MINE_REMINDER` | `3` | Distinct unmined sessions before `status` nudges you to mine. |
+
+## Scope
+
+super-skill is deliberately the **package-manager** form (milestones M0 + WS). The
+self-learning loop — automatically optimizing, distilling, and promoting skills
+(milestones M1–M5) — is a **deferred research track**: a measurement of real usage
+did not clear the threshold that would justify building it, so v1 is frozen as a
+package manager with audit and rollback. It does not self-evolve your skills, and
+this README does not imply it does.
+
+## FAQ
+
+**Does super-skill run or change my skills' behavior?**
+No. It manages the files (version, audit, rollback, integrity) and never edits a
+skill's content on its own. Approving a candidate promotes a draft *you* reviewed.
+
+**Will it touch `~/.claude/skills` without asking?**
+Three commands write there — `approve` (promote a reviewed candidate), `rollback`,
+and `doctor --fix`. `seed` reads your skills into the registry but never modifies
+them; `status`/`list`/`show`/`explain`/`doctor` are read-only.
+
+**Are my secrets safe in captured sessions?**
+Redaction runs *before* any write: secret values and private paths never reach the
+log. Capture is off until you wire it (`super-skill hooks-config`).
+
+**Do I need PyPI for the plugin to work?**
+The plugin calls the `super-skill` CLI on your PATH. Until the PyPI release,
+install the CLI from source: `uv tool install git+https://github.com/sdsrss/super-skill`.
+
+**Does it support Codex?**
+Yes — the same CLI plus a `codex/` install package for `~/.agents/skills`. A Codex
+*Target Adapter inside the CLI* is a later item; distributing skills to Codex needs
+no extra step since they already live in `~/.agents/skills`.
+
+## Develop
+
+Uses [uv](https://docs.astral.sh/uv/). Python 3.12.
+
+```bash
+uv sync                       # venv + deps
+uv run pytest                 # tests
+uv run ruff check .           # lint
+uv run mypy super_skill/      # typecheck
+```
+
+## License
+
+[MIT](LICENSE) © sdsrss