Install & first run
Ghost Skills is a Python CLI. Not on PyPI yet — install from GitHub. It reads the Claude Code history you already have; nothing leaves your machine during ingest or scan.
$ ghost init
One guided command sets everything up and never crashes on a fresh machine. It checks your PATH, stores your Anthropic API key (opt-in, chmod 600, validated by a free metadata ping), detects Claude Code and your history, then runs a first scan and shows your candidates.
ghost doctor anytime for a full health check.Three commands. That's the whole thing.
Ghost Skills turns the failures you already lived through into skills your agent reuses. The loop is three commands — the rest is inspection and control.
No hooks are installed. ghost deploy writes plain SKILL.md files that Claude Code discovers natively — nothing is silent.
Command reference
Every command accepts --db (default ~/.ghost/ghost.db). Commands that take an identifier accept a skill id, a candidate id, or a slug — Ghost resolves it and tells you how.
~/.claude/projects/**/*.jsonl into SQLite. Idempotent, streaming. --rebuild re-ingests (refuses if files vanished from disk, so no session is lost silently).src_file:src_line.SKILL.md. One LLM call, a Pitfalls section where each pitfall cites the failure that proves it, plus a self-critique. Verdict SKILL or SKIP. Refuses to create a duplicate — --force regenerates and disables the old one.~/.claude/skills/ (global) or the project's .claude/skills/. One skill per candidate (the newest). --dry-run shows without writing.--budget, default $2; --top, default 10). No auto-deploy — triage stays human.--public enters the lift-ranked registry. Lift is measured after and shows in ghost earnings.preview prints the exact payload that would be sent. Only aggregate counts — never code, paths, or prompts.How it works
Two behaviors that look like bugs — the SKIP and "no measurable lift" — are exactly what keeps the tool honest.
1 · Scars
ghost scan reads your ingested history and finds three shapes of scar: failure loops (the agent hit the same error several times before converging — the convergence is the knowledge), human overrides (you corrected it — expensive signal), and repeated sequences (a pattern to capture once). Every candidate keeps a stable link to the raw events, so you can always trace back to the proof.
2 · Distillation
ghost distill sends the redacted trace to an LLM that condenses it into a SKILL.md: when to use it, the procedure, and a Pitfalls section where every pitfall cites the failure that proves it. Nothing invented — if the trace proves nothing non-obvious, nothing is written.
3 · SKIP is a feature
Many candidates return SKIP: what the agent already did well is generic and worthless. A catalog that kept everything would drown you in noise. An honest SKIP beats a hollow skill — the triage is the value.
4 · Lift, measured
A skill only matters if it changes what your agent produces. Ghost measures it instead of assuming it — see below.
Measuring lift
The success criterion is a resolved task (a grader passes), not "a commit was produced". Runs cut by budget or timeout are their own category — never failures. If the with/without distributions overlap, the verdict is "no measurable lift" — a result, not a bug. A skill that always showed positive lift would be broken.
Privacy & security
Everything lives in ~/.ghost/ (dir 0700, db 0600). ingest, scan, show, skills, deploy touch nothing on the network. Only distill/validate/bench call the Anthropic API, with your key.
Redaction before any send — fail closed
Before a trace leaves for distillation it passes a fail-closed redactor: when in doubt, mask. Only counts are logged, never values. Over-redaction is accepted by contract; under-redaction is a bug.
Telemetry — off by default
Opt-in only, HTTPS required, strict allowlist. Even enabled, it sends only aggregate command names and error classes — never your code, paths, prompts, or skill contents. ghost telemetry preview prints the exact payload before anything is sent.
The collective memory
Your own skills are free forever, on your own key. The paid product is access to the collective memory — ranked by measured lift, never by download count. It's metered in unlocks: the first time a distinct community skill enters your library in the billing period. Re-using a skill you already unlocked never re-counts.
Authorizing the CLI — the device flow
ghost login never asks for a password. It prints a short code (like K7Q2-9FMX) and opens ghost-memory.com/device in your browser. Enter the code there, click Authorize this device, and the terminal picks up the token on its own — stored in ~/.ghost/ghost_token (0600), never your Anthropic key. The code expires 10 minutes after you run the command; if it lapses, run ghost login again for a fresh one. ghost whoami confirms the connected account.
Tiers: Free $0 (5 lifetime unlocks to try) · Pro $29/mo (200 unlocks) · Team $95/mo (1,000) · Scale $195/mo (4,000, private registry) — then usage-based overage. Hitting the quota is a clear message, never a crash: your local retrieve and already-unlocked skills keep working.
Account & consumption
Read your real account state — computed from live data, never invented. All of these degrade gracefully offline (last-known state, flagged as possibly stale) and never crash.
Contribute & earn
On a paid plan you don't just use the collective memory — you earn from it. Publish skills that work and a share of subscription revenue (50%, paid for measured lift × adoption) comes back to you. Publishing runs a mandatory fail-closed secret scan and shows the exact redacted diff before anything leaves; skills are private by default.
FAQ
ghost: command not found
Installed but not on your PATH (often ~/.local/bin). Run uv tool update-shell and reopen your terminal. ghost init and ghost doctor both detect and explain this.
ghost scan finds no candidates
Almost always the history: empty base (run ghost ingest), no Claude Code history yet, or a history too smooth to have scars. That last one is normal, not a bug.
distill says SKIP / bench says "no lift"
Both are honest results. SKIP means what the agent already did well is generic. "No lift" means that, on a baseline that actually works, the skill doesn't measurably change the outcome — proof the measurement doesn't cheat.
Does my code go over the network?
Not by default — ingest and scan are fully local. Distillation sends redacted traces to the Anthropic API with your key. Telemetry is off by default and never sends code.