super-skill-cli 0.9.2__py3-none-any.whl

super_skill_cli-0.9.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+super_skill/__init__.py,sha256=cc5oJud7loWIL4XNHAqG1wHM4a9f7dmiIW8j6Am4imA,385
+super_skill/candidate.py,sha256=ts2D0HWIjMEKG17BgOogB6MMMN8fZX4xwp6pcM01miM,7483
+super_skill/capture.py,sha256=lBxP3N3ZhEV-Ab_beOpSfx3aszdzV_k_RpkEeIlCgFg,2671
+super_skill/cli.py,sha256=H8xvzxsBQU6kXL733IqmMV3HLExDA6VijA85mrxdV68,15049
+super_skill/config.py,sha256=CgTuypnw5dWyQjznKRI6H-tZjq0ANED5qBnJ6MJk8mY,745
+super_skill/doctor.py,sha256=lw7A7KnJvp9EEii1ZOFqx9JUghXbSV-Vr5IWrnouPtw,5053
+super_skill/evallite.py,sha256=B-76wKpL33YpdkCCrekzTvxDgwkRV9ANqVcOlOxaWcA,3223
+super_skill/gate.py,sha256=fhkT9GbeXYVwAxFOuKKHGus0EEPkjvnzo-21obmhVqo,3689
+super_skill/hooks.py,sha256=sx-XOxc5wdUOJ2cq4ru2Ty3dab1U5t-oRgxxDSts8cY,1377
+super_skill/mine.py,sha256=OMkKFqVB0lopieF36K6RZTIXW_O3qO1qavZx_c_TMx0,3398
+super_skill/minestate.py,sha256=8SRVqh_0ivxl-HUI1OwDAK_dvt6wuAfbDwsjAhs5HkQ,1803
+super_skill/redact.py,sha256=ThuQ7GdPu83-yNcp9WK61PXW0jVRQnBYiI70MbThqDU,3614
+super_skill/registry.py,sha256=tOwc48hghuBNRVo_7KCGsoV67uzLeueBikVvJSUsyNo,8312
+super_skill/schemas.py,sha256=hYOVPv-Hv88rT3xKBKOAin23OdoRFGNVdiD5g0MaVXA,6380
+super_skill/seed.py,sha256=RNGr-fqOqNCSQ3zfNUCifJUU-SRacWfBWzwfiJD47n8,2457
+super_skill/skillmd.py,sha256=IsMW8SqK49soOM1VtTLowyrDkZKTHRkFIf1Yw_hkQvE,1882
+super_skill_cli-0.9.2.dist-info/METADATA,sha256=3LS0Yl2LrgLnUqK8G_19cskdpVNqRdYhtBiDKDFl3Z4,8917
+super_skill_cli-0.9.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+super_skill_cli-0.9.2.dist-info/entry_points.txt,sha256=0lRmyO-45Vmt5N8wifWeERHTTxf8hiMiUPBO04YgqlU,52
+super_skill_cli-0.9.2.dist-info/licenses/LICENSE,sha256=OW7siLAASCvvOkdUSfpledx2yHcZJlQgyOlHlUrXDpA,1063
+super_skill_cli-0.9.2.dist-info/RECORD,,

super_skill_cli-0.9.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

super_skill_cli-0.9.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+super-skill = super_skill.cli:app

super_skill_cli-0.9.2.dist-info/licenses/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.