{"id":51500105,"url":"https://github.com/ginaecho/skill-quartermaster","last_synced_at":"2026-07-07T17:30:35.588Z","repository":{"id":366129118,"uuid":"1275133476","full_name":"ginaecho/skill-quartermaster","owner":"ginaecho","description":"Non-destructive skill manager — compiles the right skill loadout per project, then demotes and hides unused skills to keep your context window lean. Never deletes without your approval.","archived":false,"fork":false,"pushed_at":"2026-06-20T10:55:54.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T12:27:19.187Z","etag":null,"topics":["agent-skills","agentic-ai","ai-agents","context-engineering","context-window","context-window-optimization","developer-tools","llm","prompt-engineering","skill-management","skill-marketplace","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ginaecho.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T09:43:25.000Z","updated_at":"2026-06-20T10:48:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ginaecho/skill-quartermaster","commit_stats":null,"previous_names":["ginaecho/skill-quartermaster"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ginaecho/skill-quartermaster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginaecho%2Fskill-quartermaster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginaecho%2Fskill-quartermaster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginaecho%2Fskill-quartermaster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginaecho%2Fskill-quartermaster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ginaecho","download_url":"https://codeload.github.com/ginaecho/skill-quartermaster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginaecho%2Fskill-quartermaster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35237753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agentic-ai","ai-agents","context-engineering","context-window","context-window-optimization","developer-tools","llm","prompt-engineering","skill-management","skill-marketplace","token-optimization"],"created_at":"2026-07-07T17:30:34.835Z","updated_at":"2026-07-07T17:30:35.575Z","avatar_url":"https://github.com/ginaecho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# skill-quartermaster\nNon-destructive skill manager — compiles the right skill loadout per project, then demotes and hides unused skills to keep your context window lean. Never deletes without your approval.\n\n\u003ch1 align=\"center\"\u003e🎖️ Quartermaster\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA non-destructive skill manager for coding agents.\u003c/strong\u003e\u003cbr\u003e\n  Compiles the right skill \u003cem\u003eloadout\u003c/em\u003e for your project, then quietly demotes and hides the skills you aren't using —\u003cbr\u003e\n  so your context window stays lean and your skill set stays relevant. \u003cstrong\u003eNothing is ever deleted without your yes.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003c!-- Replace these with real badges once published --\u003e\n  \u003cimg alt=\"status\" src=\"https://img.shields.io/badge/status-alpha-orange\"\u003e\n  \u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-blue\"\u003e\n  \u003cimg alt=\"claude code\" src=\"https://img.shields.io/badge/Claude%20Code-plugin-8A2BE2\"\u003e\n  \u003ca href=\"https://doi.org/10.5281/zenodo.21009805\"\u003e\u003cimg alt=\"DOI\" src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.21009805.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The problem\n\nThe skill ecosystem exploded. Mega-marketplaces ship hundreds of skills in one install; aggregators index tens of thousands of plugin repos. Two pains follow:\n\n- **Context cost \u0026 noise.** A large installed set clutters the model's selection space and degrades tool-selection accuracy past a few dozen skills.\n- **Curation burden.** You have to decide what to keep, what to drop, and when to write new skills — and today there isn't even a clean \"turn this one off.\" The common workaround is to *rename `SKILL.md` to `_SKILL.md`* so the parser misses it.\n\nPeople avoid cleanup tools because of one fear: **\"what if it deletes the wrong thing?\"** Quartermaster is built so that can't happen.\n\n## What it does\n\nMeasured on **851 real open-source skills** (Anthropic + community hubs — see\n[`benchmark/`](./benchmark/)):\n\n```\n851 skills installed  →  30 loaded for this project  →  ~57.5k tokens saved (96%)  →  0 deleted\n```\n\n| Claim | Evidence on the 851-skill corpus |\n|---|---|\n| Cuts the model's selection set | auto-select set **851 → 30** (28× smaller, at the ~30 sweet spot) |\n| Saves context tokens | **~59.7k → ~2.2k** indexed tokens (~57.5k saved, 96%) |\n| Never deletes | **851 → 851** files on disk, **0** deleted |\n| Fully reversible | demote→restore **byte-identical on 200/200** sampled skills |\n| Usage-driven curation | flags **809** stale skills to demote, then **737** to hide — fresh skills left active |\n| **Keeps what the task needs** | trimmed loadout is **~10× more relevant than random**; **100% recall** of specifically-needed skills at cap=30 (vs 3.5% random) |\n| **Doesn't hurt the agent** | live skill-selection A/B (`claude-opus-4-8`, 60 tasks): loadout **97%** vs full set **93%** (**+3 pts**, 100% recall) — trimming doesn't degrade which skill the model picks |\n\nFull reports: [`BENCHMARK.md`](./BENCHMARK.md) (lifecycle + savings),\n[`PERFORMANCE.md`](./PERFORMANCE.md) (capability retention — proof the token\nsavings don't drop the skills a task needs), and the live\n[A/B selection eval](./benchmark/ab_eval/) (proof the loadout doesn't degrade\nwhich skill the model picks). All reproducible from [`benchmark/`](./benchmark/).\n\n### Does trimming hurt the agent? (live A/B)\n\nSaving tokens is only worth it if the agent still picks the right skill. The\n[`benchmark/ab_eval/`](./benchmark/ab_eval/) harness puts a real model\n(`claude-opus-4-8`) in the loop and measures **skill-selection accuracy** on\ntasks with known-correct skills, comparing the **full 851-skill set** against the\n**~30-skill loadout**. Because both conditions share the same task wording, the\nshared confounds cancel in the A−B difference — the hypothesis is **loadout ≥\nfull**.\n\n```bash\npip install anthropic \u0026\u0026 export ANTHROPIC_API_KEY=sk-ant-...\n\n# build the corpus once (clones real skill repos, dedupes into \u003cname\u003e/SKILL.md)\ngit clone --depth 1 https://github.com/davila7/claude-code-templates /tmp/c8\ngit clone --depth 1 https://github.com/anthropics/skills              /tmp/corpus\npython3 benchmark/build_corpus.py /tmp/c8 /tmp/corpus --out /tmp/skillhub\n\n# run the A/B (uses /tmp/c8 for the gold category labels)\npython3 benchmark/ab_eval/run_ab_eval.py /tmp/skillhub /tmp/c8 --n 60\n# writes benchmark/ab_eval/AB_RESULTS.md\n```\n\nProvider-agnostic — pick any model/provider, not just Anthropic:\n`--provider openai --model gpt-4o`, any OpenAI-compatible endpoint via\n`--base-url` (OpenRouter/Groq/Azure, or a **local** Ollama/vLLM/LM Studio), or\ndrive a real agent CLI with `--provider command --command \"claude -p\"` /\n`\"copilot -p\"`. See [`benchmark/ab_eval/`](./benchmark/ab_eval/).\n\n\u003c!-- AB-RESULTS:START — paste the headline from benchmark/ab_eval/AB_RESULTS.md after the live run --\u003e\n**Live run** — `claude-opus-4-8`, 60 tasks (seed 7), full menu 840 skills, loadout cap 30:\n\n| Condition | menu size | gold-hit accuracy |\n|---|--:|--:|\n| **A — full installed set** | 840 | **93%** |\n| **B — Quartermaster loadout** | ≤30 | **97%** |\n| Δ (loadout − full) | | **+3 pts** |\n\nRecall (gold skill present in the loadout): **100%** · selection accuracy given present: **97%**.\n\n**Trimming to the loadout did not hurt selection (97% vs 93%)** — the agent finds the\nright skill at least as often with ~30 skills as with 840, at a fraction of the context\ncost. Full report: [`benchmark/ab_eval/AB_RESULTS.md`](./benchmark/ab_eval/AB_RESULTS.md).\n\u003c!-- AB-RESULTS:END --\u003e\n\nQuartermaster manages the **lifecycle** of your skills instead of their content. It moves skills along a tiered ladder based on what you actually use — and keeps a human veto on anything irreversible.\n\n| State | In context? | Auto-loadable? | You can invoke? | On disk? |\n|---|:---:|:---:|:---:|:---:|\n| **active** | ✅ indexed | ✅ | ✅ | ✅ |\n| **demoted** | ✅ indexed | ❌ | ✅ manual | ✅ |\n| **hidden** | ❌ | ❌ | ❌ | ✅ |\n| **archived** | ❌ | ❌ | ❌ | ✅ *(outside active roots)* |\n| **deleted** | ❌ | — | — | ❌ *(only after you approve)* |\n\nEvery transition is **logged and reversible**. Demote and hide happen automatically; **delete never does**.\n\n## Quick start\n\n```bash\n# Add the marketplace\n/plugin marketplace add \u003cyour-org\u003e/skill-quartermaster\n\n# Install\n/plugin install quartermaster@skill-quartermaster\n```\n\nOnce installed you get the `quartermaster` skill plus slash commands\n(`/qm-status`, `/qm-compile`, `/qm-review`, `/qm-restore`) and the `qm` CLI:\n\n```bash\nqm status              # show every skill, its state, last-used, token cost\nqm status --layers     # include metadata layer and priority\nqm runtimes            # list supported runtime adapters\nqm runtime-setup codex # write local setup files for a runtime adapter\nqm compile \"\u003cintent\u003e\"  # build an active loadout for this project\nqm review              # see proposed demotions/promotions and approve them\nqm restore \u003cskill\u003e     # bring anything back from demoted/hidden\nqm demote \u003cskill\u003e      # take a skill out of auto-selection (manual-only)\nqm hide \u003cskill\u003e        # remove a skill from context entirely\nqm archive \u003cskill\u003e --yes # move a skill to reversible archive storage\nqm log                 # print the audit trail of every change\nqm history \u003cskill\u003e     # inspect historical usage/selection metadata\nqm conflicts           # report explicit/inferred skill conflicts\nqm sources             # list curated external skill repos to consider\nqm intake \u003crepo\u003e --dry-run # safely scan a local external skill repo\nqm delete \u003cskill\u003e --yes  # human-gated removal (the only destructive action)\n\n# Authoring arm — turn recurring gaps into new skills\nqm gap \"\u003cneed\u003e\"        # record a capability gap (a need with no matching skill)\nqm gaps                # cluster gaps; recommend new skills to author\nqm author \u003cname\u003e       # scaffold a probationary skill (hand off to skill-creator)\nqm graduate \u003cskill\u003e    # end probation once a new skill has proven useful\n\n# Feedback \u0026 undo\nqm feedback \"\u003cgripe\u003e\"  # route a plain-language complaint to the right lever\nqm revert              # undo the last automatic change (one-click revert)\n```\n\n\u003e Quartermaster only ever *toggles states* and *proposes* changes. It will not remove a skill from disk unless you explicitly confirm with `--yes`.\n\n### Try it without installing\n\nThe CLI is pure-Python (stdlib only). Point it at any folder of skills:\n\n```bash\nexport QM_SKILLS_DIR=~/.claude/skills      # or your project's .claude/skills\npython3 bin/qm status\n```\n\nQuartermaster is runtime-aware. Claude Code remains the default, and Phase 0\nalso exposes adapter names for Codex, GitHub Copilot CLI, VS Code, and generic\ncommand agents:\n\n```bash\nqm runtimes\nqm runtime-setup codex\nqm runtime-setup --all\nqm --runtime claude status\nqm --runtime generic status\nQM_RUNTIME=codex qm status\n```\n\nNon-Claude adapters use Quartermaster-owned state metadata (`qm-state`),\nworkspace-local setup files, and exported loadout manifests as the compatibility\nlayer. Runtime setup writes local guidance/manifests without needing vendor\ncredentials:\n\n```bash\nqm runtime-setup codex\nqm runtime-setup copilot\nqm runtime-setup vscode\nqm runtime-setup generic\n```\n\nSkills can optionally declare Quartermaster metadata in frontmatter:\n\n```yaml\nqm-layer: guardrail\nqm-priority: 100\nqm-tags: security, secrets\nqm-risk: network, production\nqm-provides: secret-scan\nqm-requires-guardrails: security-review\nqm-conflicts-with: unsafe-deploy\n```\n\nAll metadata is optional. Existing skills without these keys still load, and\nQuartermaster infers a conservative default layer for status/reporting.\n\n### Trusted external skill intake\n\nQuartermaster can grow your skill shelf from public Git repositories, but it\ndoes not blindly install them. Clone candidate repos yourself, then scan the\nlocal checkout:\n\n```bash\nqm sources\ngit clone --depth 1 \u003crepo-url\u003e /tmp/skills-source\nqm intake /tmp/skills-source --dry-run\nqm intake /tmp/skills-source --import-to .claude/skills --yes\n```\n\nThe intake scanner never executes candidate code. It reads `SKILL.md` files,\nscores high-value skills, flags suspicious install/shell/exfiltration patterns,\nand imports only accepted candidates after explicit `--yes`.\n\n`qm compile` now explains loadouts by layer and writes a runtime loadout\nmanifest under `$QM_HOME/loadouts/` when applied, so non-Claude runtimes can\nconsume the same selected skill set through their adapter.\n\nLocal state (usage telemetry, audit log, and the historical skill dictionary)\nlives under `~/.quartermaster/`\n(override with `QM_HOME`). Nothing ever leaves your machine.\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[Project intent + style] --\u003e B[Intent Compiler]\n    B --\u003e C[Active loadout ~30 skills]\n    C --\u003e D[Run tasks]\n    D --\u003e E[Usage telemetry + feedback]\n    E --\u003e F[Policy Engine - proposals only]\n    F --\u003e G[Human approval gate]\n    G --\u003e H[Update registry / state]\n    H --\u003e C\n    F -. capability gap .-\u003e I[Authoring arm]\n    I --\u003e H\n```\n\n1. **Registry** — an index of every skill on disk with its state, description embedding, and last-used timestamp.\n2. **Intent compiler** — selects an initial active set from your project intent + style file, kept near the ~30-skill accuracy sweet spot.\n3. **Telemetry** — logs which skills actually fire per task (via skill hooks). Local-only; nothing leaves your machine.\n4. **Historical dictionary** — records first/last seen, usage count, selection count, state transitions, metadata, and useful intents per skill.\n5. **Policy engine** — *proposes* demotions (unused for N days), promotions (you keep invoking a demoted skill), and authoring (repeated gaps with no matching skill).\n6. **Human gate** — batched approvals; deletion only after long-demoted **and** explicit confirmation.\n7. **Authoring arm** — hands genuine gaps to `skill-creator`, admitting new skills as `active, probationary`.\n\nUnder the hood these states map to the selected runtime's primitives where\navailable. Claude Code uses its native skill frontmatter flags; generic and\nfuture adapters use Quartermaster-owned metadata until native integration is\nimplemented.\n\n## Why non-destructive matters\n\nYou're trusting a tool to touch your skills. Quartermaster's entire design is built around that trust:\n\n- **Demote, don't delete** — unused skills drop out of the model's attention and out of context, but stay fully on disk and recoverable.\n- **One-command restore** — `qm restore \u003cskill\u003e` reverses any single change; `qm revert` walks back the last N automatic changes from the audit trail.\n- **Human-gated deletion** — the only path to removal runs through an explicit approval; `qm revert` deliberately refuses to undo a deletion or silently delete a skill.\n- **Full audit log** — every state change (including each revert) is recorded and inspectable via `qm log`.\n\n## Roadmap\n\n| Phase | Scope | Status |\n|---|---|---|\n| **v0** | Lifecycle core: registry, state toggles, `qm status` + token-saved report | ✅ shipped |\n| **v0.2** | Usage telemetry (PreToolUse hook) + demote-if-unused proposals + batched approvals (`qm review`) | ✅ shipped |\n| **v0.3** | Intent compiler (`qm compile` — keyword loadout from project intent) | ◐ basic |\n| **v0.4** | Authoring arm: gap detection (`qm gap`/`qm gaps`) → `skill-creator` handoff (`qm author`) → probationary admission + graduation | ✅ shipped |\n| **v0.5** | Natural-language feedback (`qm feedback`) → style file / gap / promote / demote signals | ✅ shipped |\n| **v1.0** | One-click revert (`qm revert`), full audit trail, marketplace listing; semantic-embedding compiler + dashboard | ◐ partial |\n\nWe ship the lifecycle half first on purpose — the compiler and authoring arm only earn their place once the simple half has users.\n\n## Project layout\n\n```\n.claude-plugin/\n  plugin.json          # plugin manifest (skill + commands + hooks)\n  marketplace.json     # one-command install manifest\nskills/quartermaster/  # the meta-skill that teaches Claude to drive qm\ncommands/              # /qm-status, /qm-compile, /qm-review, /qm-restore\nhooks/                 # PreToolUse usage telemetry (local-only)\nqm/                    # the pure-Python CLI\n  registry.py          #   the shelf: scan skills, derive state from frontmatter\n  transitions.py       #   non-destructive state changes + audit logging\n  policy.py            #   the policy engine — proposes, never executes\n  compile.py           #   intent compiler (keyword loadout)\n  authoring.py         #   authoring arm: gap clustering + skill scaffolding\n  feedback.py          #   route plain-language complaints to the right lever\n  history.py           #   one-click revert from the audit trail\n  store.py             #   local audit log + usage telemetry\n  report.py            #   status table + token-saved report\n  cli.py               #   argparse dispatch\nbin/qm                 # zero-install entry point\ntests/                 # pytest suite\n```\n\nRun the tests with `python3 -m pytest`.\n\n## Contributing\n\nContributions welcome — especially telemetry hooks, policy rules, and adapters for other harnesses (Cursor, Copilot, Zed) via the open Agent Skills standard. Please open an issue describing the change before large PRs.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\u003csub\u003eQuartermaster manages your skills. It never loses them.\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fginaecho%2Fskill-quartermaster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fginaecho%2Fskill-quartermaster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fginaecho%2Fskill-quartermaster/lists"}