release: v2.12.0 — consolidated release notes, version bump, docs-site regeneration

- CHANGELOG.md gains the [2.12.0] entry (first tagged release since v2.9.0):
  consolidates the previously documented but untagged v2.10.0-v2.11.2 work,
  all post-2.11.2 merges, and the full 17-issue triage sweep; the ten stacked
  [Unreleased] sections are demoted into the 2.12.0 body so the Release
  workflow tags and publishes the whole span. Verified parseable with
  scripts/extract_release_notes.py (version 2.12.0, 554-line body).
- Version markers bumped to 2.12.0: marketplace.json metadata,
  CLAUDE.md current-version header + footer.
- Counters trued to the derived values (380 skills / 96 plugins / 20 domains /
  706 tools / 823 refs / 114 agents / 138 commands) in README badges + prose,
  CLAUDE.md, marketplace.json, and the long-stale mkdocs.yml/docs/index.md
  site description (was still claiming 345/78/17).
- Docs site regenerated via scripts/generate-docs.py (568 generated pages;
  new pages for the recently merged plugins); codex/gemini mirrors resynced;
  mkdocs build verified locally with the same plugin set static.yml uses
  (670 HTML pages, no errors).
- Fix: the three hivemind worker personas (assets/agents/{coder,scout,tester}.md,
  merged via #979 while Actions was not triggering) lacked the frontmatter
  `name:` field and hard-failed the blocking G10 gate — named
  hive-coder/hive-scout/hive-tester; 645 files now scan with 0 errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qgc6RYXWJPr5oW9DHU7zR4
This commit is contained in:
Claude 2026-08-24 20:35:06 +00:00
parent 9109be93c8
commit d928ec95d5
No known key found for this signature in database
34 changed files with 896 additions and 62 deletions

View file

@ -8,8 +8,8 @@
"homepage": "https://github.com/alirezarezvani/claude-skills",
"repository": "https://github.com/alirezarezvani/claude-skills",
"metadata": {
"description": "379 production-ready skills across 20 domains (engineering, engineering-core, marketing, product, c-level, c-level-agents, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, loop-library, plus standards). 706 Python tools, 823 reference guides, 111 agents (cs-* + personas), 131 slash commands across 96 marketplace plugins. v2.11.2 vendors engineering/skillopt-sleep — a verbatim copy of microsoft/SkillOpt's stdlib-only skillopt_sleep engine + Claude Code plugin surface, giving a local agent a nightly gated self-improvement cycle (read-only session harvest -> mine -> offline replay -> held-out-gated CLAUDE.md/SKILL.md edits -> staged for explicit /skillopt-sleep adopt). productivity/fable-goal (unreleased, post-v2.11.1) converts a rambling description of a desired outcome into one polished /goal prompt for a fresh autonomous session. v2.11.1 turns product-team and project-management into agent-harness domains: fork-orchestrators with deterministic goal routers, a Jira MCP snapshot bridge (Kanban flow metrics + Monte Carlo forecasting), a delegation-governance loop gate, a continuous-discovery cadence tracker, and an Opportunity Solution Tree linter, with /cs:pm and /cs:product command families. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
"version": "2.11.2"
"description": "380 production-ready skills across 20 domains (engineering, engineering-core, marketing, product, c-level, c-level-agents, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, loop-library, plus standards). 706 Python tools, 823 reference guides, 111 agents (cs-* + personas), 131 slash commands across 96 marketplace plugins. v2.11.2 vendors engineering/skillopt-sleep — a verbatim copy of microsoft/SkillOpt's stdlib-only skillopt_sleep engine + Claude Code plugin surface, giving a local agent a nightly gated self-improvement cycle (read-only session harvest -> mine -> offline replay -> held-out-gated CLAUDE.md/SKILL.md edits -> staged for explicit /skillopt-sleep adopt). productivity/fable-goal (unreleased, post-v2.11.1) converts a rambling description of a desired outcome into one polished /goal prompt for a fresh autonomous session. v2.11.1 turns product-team and project-management into agent-harness domains: fork-orchestrators with deterministic goal routers, a Jira MCP snapshot bridge (Kanban flow metrics + Monte Carlo forecasting), a delegation-governance loop gate, a continuous-discovery cadence tracker, and an Opportunity Solution Tree linter, with /cs:pm and /cs:product command families. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
"version": "2.12.0"
},
"plugins": [
{

View file

@ -1223,18 +1223,18 @@
"category": "engineering-advanced",
"description": "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality (precision@k, recall@k, NDCG). Examples: 'design a RAG system for our docs', 'what chunk size should I use for this corpus', 'evaluate my retriever against ground truth'. NOT for general LLM cost tuning (use llm-cost-optimizer) or agent loops over retrieval (use agenthub)."
},
{
"name": "run",
"source": "../../engineering/agenthub/skills/run",
"category": "engineering-advanced",
"description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end."
},
{
"name": "run",
"source": "../../engineering/autoresearch-agent/skills/run",
"category": "engineering-advanced",
"description": "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration."
},
{
"name": "run",
"source": "../../engineering/agenthub/skills/run",
"category": "engineering-advanced",
"description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end."
},
{
"name": "runbook-generator",
"source": "../../engineering/skills/runbook-generator",

View file

@ -1 +1 @@
../../engineering/autoresearch-agent/skills/run
../../engineering/agenthub/skills/run

View file

@ -1,7 +1,7 @@
{
"version": "1.0.0",
"name": "gemini-cli-skills",
"total_skills": 427,
"total_skills": 430,
"skills": [
{
"name": "README",
@ -1048,6 +1048,11 @@
"category": "engineering-advanced",
"description": "Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for authoring Claude Code Workflow-tool .js scripts (workflow-builder), N-agent tournaments on one task (agenthub), single-file metric optimization (autoresearch-agent), or discovering published loop recipes (loop-library)."
},
{
"name": "agent-memory",
"category": "engineering-advanced",
"description": "Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead \u2014 or when asking why the agent keeps re-learning the same correction, why a remembered rule is wrong, or where a memory line came from. Implements a four-tier store (L0 transcripts / L1 candidates / L2 project context / L3 stable persona) where promotion is earned by recurrence across sessions and days, never by one confident statement, and nothing reaches a committed file without a human adopting it."
},
{
"name": "agent-workflow-designer",
"category": "engineering-advanced",
@ -1228,6 +1233,11 @@
"category": "engineering-advanced",
"description": "Helm chart development agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw \u2014 chart scaffolding, values design, template patterns, dependency management, security hardening, and chart testing. Use when: user wants to create or improve Helm charts, design values.yaml files, implement template helpers, audit chart security (RBAC, network policies, pod security), manage subcharts, or run helm lint/test."
},
{
"name": "hivemind",
"category": "engineering-advanced",
"description": "Orchestrate free opencode workers from Claude Code to cut token costs. Use when delegating grunt work to a single worker or a parallel swarm (scout/coder/tester) with worktree isolation, benchmarking against opencode, or when the user says \"spawn a worker\", \"swarm\", \"delegate to opencode\", or \"/oc\"."
},
{
"name": "hub-init",
"category": "engineering-advanced",
@ -1368,6 +1378,11 @@
"category": "engineering-advanced",
"description": ">"
},
{
"name": "skill-doctor",
"category": "engineering-advanced",
"description": "Use when the user wants their agent setup graded from real conversation history, asks which installed skills are actually working, or wants evidence-backed skill edits \u2014 scores recent local Claude Code / Codex sessions against efficiency and code-quality rubrics, then drafts skill changes gated by a deterministic aggregator and renders one local shareable report."
},
{
"name": "skill-security-auditor",
"category": "engineering-advanced",
@ -2177,7 +2192,7 @@
"description": "Engineering resources"
},
"engineering-advanced": {
"count": 88,
"count": 91,
"description": "Engineering-advanced resources"
},
"finance": {

View file

@ -0,0 +1 @@
../../../engineering/agent-memory/skills/agent-memory/SKILL.md

View file

@ -0,0 +1 @@
../../../engineering/hivemind/SKILL.md

View file

@ -0,0 +1 @@
../../../engineering/skill-doctor/skills/skill-doctor/SKILL.md

View file

@ -5,7 +5,89 @@ All notable changes to the Claude Skills Library will be documented in this file
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased] — agent-launcher: session-goal domain plugin for Claude Managed Agents (PR #961, merged 2026-08-21)
## [2.12.0] - 2026-08-24 — consolidated release: 20 domains, 380 skills, full issue-triage sweep
**First tagged release since v2.9.0.** Versions 2.10.02.11.2 were documented in
CLAUDE.md/README at the time but never entered here, so the Release workflow never
tagged them; this entry consolidates everything since the v2.9.0 tag — the
previously documented v2.10.x/v2.11.x work plus all post-2.11.2 merges. Headline
counters at this release: **380 skills · 96 marketplace plugins · 20 domains ·
706 Python tools · 823 reference docs · 114 agents · 138 slash commands**
(derived and gated by `scripts/derive_counters.py --check`).
### Added — consolidated from the untagged v2.10.0v2.11.2 releases
- **markdown-html/** domain complete (v2.10.0v2.10.3): orchestrator +
design-system foundation, then `md-document` (long-form), `md-review`
(2-col code review), `md-slides` (single-file deck with presenter mode).
- **engineering/agent-harness** (v2.11.0): manifest builder + goal compiler +
loop controller turning any domain into a bounded, self-verifying agent loop;
agentic-readiness audit of both engineering folders.
- **product-team + project-management as agent-harness domains** (v2.11.1):
fork-orchestrators, deterministic goal routers, Jira snapshot bridge with
Monte Carlo forecasting, delegation-governance loop gate, discovery cadence
tracker + OST linter; audit record `audit/pm-product-agentic-2026-07/`.
- **engineering/skillopt-sleep** (v2.11.2): vendored microsoft/SkillOpt nightly
self-improvement engine with 23 documented hardening deviations.
### Added — post-v2.11.2 merges in this release
- **agent-launcher/** — 20th top-level domain: Claude Managed Agent launcher
(full detail in its section below).
- **engineering/memory-engineering** — design/price/audit agent memory systems
(cost profiler, architecture picker, density auditor, forgetting-policy linter).
- **engineering/agent-memory** — four-tier (L0L3) promotion-gated memory ladder
over Claude Code hooks; nothing reaches a CLAUDE.md without a human adopt.
- **engineering/human-gate**, **engineering/book-to-skill**,
**engineering/hivemind** (PR #979), **productivity/fable-goal**,
**productivity coverage expansion** (weekly-review, deep-work, meetings +
public audit `audit/productivity-2026-07/`),
**marketing local-seo-manager**, code-reviewer language expansion —
detailed sections below.
- **c-level-agents/** promoted to its own top-level domain directory (issue #949).
### Fixed — full reported-issue triage sweep (PRs #972, #973, #982)
All 17 open issues driven to a final state; the 14 resolvable ones fixed and closed:
- **#954** — 39 `plugin.json` manifests carried non-spec `source`/`attribution`
keys that made Claude Code reject the whole manifest (40% of the marketplace
uninstallable). Keys relocated to `.claude-plugin/authoring-notes.json`
sidecars; `check_plugin_json.py` now hard-fails any recurrence in CI.
- **#949** — `c-level-skills` never loaded because `c-level-agents` was nested
inside its marketplace source; moved to a top-level directory.
- **#885** — plugin skills shadowing built-in commands (`status`, `review`,
`init`, `resume`) renamed across four plugins (`memory-status`,
`pw-init`/`pw-review`, `hub-init`/`hub-status`, `ar-status`/`ar-resume`);
new blocking CI gate `scripts/check_skill_names.py` + rule in
SKILL-AUTHORING-STANDARD.md.
- **#969** — `UnicodeEncodeError` on legacy Windows codepages: nine scripts now
reconfigure stdout/stderr to UTF-8; `PYTHONUTF8=1` documented.
- **#968** — Windows symlink-checkout caveat documented (INSTALLATION.md
"Windows Notes" + README pointer).
- **#933** — all dead links to the maintainer-local `megaprompts/` tree
(~75 files incl. the docs site) replaced with annotated plain text.
- **#931** — DynamoDB on-demand pricing corrected to post-Nov-2024 rates.
- **#924** — plugin hook commands quote `"${CLAUDE_PLUGIN_ROOT}"` (space-safe).
- **#978** — playwright-pro's TestRail/BrowserStack MCP servers (which could
never start — dependencies never installed) are now a documented opt-in
instead of a permanent `Failed to connect` pair for every user.
- **#977** — two agents shipping without YAML frontmatter, repaired via the
G10 frontmatter gate work (PR #936).
- Spam/out-of-scope issues #925, #960, #923, #951 closed with rationale;
proposals #910, #952, #962 triaged with approval/scoping replies;
superseded PRs #932/#966 closed with credit.
### CI
- New blocking gates since v2.9.0: built-in-shadowing skill names (#885),
frontmatter YAML validation (G10), retired-model lint (G7), path linter G1
and script smoke G8 flipped blocking, plugin-manifest key rejection (#954),
marketplace description 1024-char cap (Copilot CLI, PR #964).
The sections below — formerly stacked as `[Unreleased]` — are part of this release.
### agent-launcher: session-goal domain plugin for Claude Managed Agents (PR #961, merged 2026-08-21)
### Added — `agent-launcher/` (new top-level domain, 19th)
@ -52,7 +134,7 @@ you", optionally self-grading each firing via a nested outcome), or a
- Distinct from `engineering/agent-harness` (generic bounded loop over any repo
domain) and `engineering/write-a-skill` (authors Claude Code skills, not CMAs).
## [Unreleased] — human-gate: batched human review as a verification artifact (this PR)
### human-gate: batched human review as a verification artifact (this PR)
### Audited — `petergyang/human-review`
@ -207,7 +289,7 @@ commands 118 → 119, plugins 89 → 90, engineering row 85 → 86
---
## [Unreleased] — book-to-skill: document → knowledge-base skill → plugin (this PR)
### book-to-skill: document → knowledge-base skill → plugin (this PR)
### Added — `engineering/book-to-skill`
@ -313,7 +395,7 @@ skills 362 → 363, tools 644 → 663, refs 741 → 746, agents 102 → 103, com
---
## [Unreleased] — fable-goal: ramble → autonomous /goal prompt (previous PR)
### fable-goal: ramble → autonomous /goal prompt (previous PR)
### Added — `productivity/fable-goal`
@ -337,7 +419,7 @@ skills 357 → 358 (this PR also trues up pre-existing engineering-row drift
355 → 357), tools 602 → 603, refs 731 → 732, commands 109 → 110, plugins
83 → 84; plus a stale "711 reference docs" claim in README line 30 fixed to 732.
## [Unreleased] — housekeeping: CHANGELOG backfill + per-domain counter validation
### housekeeping: CHANGELOG backfill + per-domain counter validation
### Added — `derive_counters.py` per-domain table validation
@ -364,7 +446,7 @@ Backfilled, newest-first:
- **`engineering-team/skills/named-persona-adversarial-review`** (PR #867, superseding #866 by @YuhaoLin2005) — code review through named, sourced engineering philosophies with confidence-leveled attribution and an anti-fabrication rule for quotes.
- **`productivity/roast`** (PR #865) — 5-angle adversarial idea panel (Critic/Champion/Analyst/Investigator/Customer) → one GO/RESHAPE/KILL verdict, with a weighted veto-gated synthesizer + cheapest-48h-test designer.
## [Unreleased] — local-seo-manager: local / Map-Pack SEO skill (this PR)
### local-seo-manager: local / Map-Pack SEO skill (this PR)
### Added — `marketing-skill/skills/local-seo-manager`
@ -385,7 +467,7 @@ plumbing, cleaning, electrical).
- No `plugin.json` / marketplace entry needed — the `marketing-skills` plugin globs `./skills`.
- Counters: 352 → 353 skills, 590 → 593 Python tools, 718 → 721 references.
## [Unreleased] — newgen audit follow-up: P0 fixes, path sweep, CI guards
### newgen audit follow-up: P0 fixes, path sweep, CI guards
### Deprecated / Removed Skills (migration notes)
@ -402,7 +484,7 @@ Also restructured (no content change): `engineering/universal-scraping-architect
moved its SKILL.md from plugin root to the standard `skills/universal-scraping-architect/`
layout. Marketplace source path is unchanged.
## [Unreleased] — code-reviewer: C-specific smell detector + fixtures
### code-reviewer: C-specific smell detector + fixtures
### Added — language-specific smell pack for C (this PR)
@ -426,7 +508,7 @@ Verification: all 6 fixtures (C# / Java / C × smells / clean) match their commi
---
## [Unreleased] — code-reviewer: 6 new languages + analyzer wiring + doc sync
### code-reviewer: 6 new languages + analyzer wiring + doc sync
### Added — language coverage 7 → 13 (PR #769)
@ -463,7 +545,7 @@ Verification: `python3 scripts/code_quality_checker.py --help` now lists all 14
---
## [Unreleased] — Mistral Vibe cross-platform installation (closes #705)
### Mistral Vibe cross-platform installation (closes #705)
### Added

File diff suppressed because one or more lines are too long

View file

@ -1,6 +1,6 @@
# Claude Code Skills & Plugins — Agent Skills for Every Coding Tool
**379 production-ready Claude Code skills, plugins, and agent skills for 13 AI coding tools.**
**380 production-ready Claude Code skills, plugins, and agent skills for 13 AI coding tools.**
The most comprehensive open-source library of Claude Code skills and agent plugins — also works with OpenAI Codex, Gemini CLI, Cursor, and 9 more coding agents. Reusable expertise packages covering engineering, DevOps, marketing (incl. AEO — Answer Engine Optimization for LLM citation), security (PreToolUse hooks), compliance, C-level advisory (incl. founder-mode CFO/CMO/CRO/CPO/COO/CHRO/CISO/GC/CDO/CAIO/CCO/VPE personas + 21 /cs:* slash commands), productivity (capture/email/reflect/weekly-review/deep-work/meetings), an academic research stack (litreview/grants/dossier/patent/syllabus/pulse/notebooklm/deep-research + hybrid router), and enterprise Research Operations (clinical-research/research-finance/market-research/product-research, v2.9.0).
@ -10,10 +10,10 @@ The most comprehensive open-source library of Claude Code skills and agent plugi
[^vibe]: Mistral Vibe is also **BYO-sync tier**: the repo ships a pre-generated `.vibe/skills/claude-skills/` tree, run `./scripts/vibe-install.sh` once locally to install into `~/.vibe/skills/`. Same agentskills.io SKILL.md standard — no format conversion. Docs: <https://docs.mistral.ai/mistral-vibe/agents-skills>.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Skills](https://img.shields.io/badge/Skills-379-brightgreen?style=for-the-badge)](#skills-overview)
[![Agents](https://img.shields.io/badge/Agents-111-blue?style=for-the-badge)](#agents)
[![Skills](https://img.shields.io/badge/Skills-380-brightgreen?style=for-the-badge)](#skills-overview)
[![Agents](https://img.shields.io/badge/Agents-114-blue?style=for-the-badge)](#agents)
[![Personas](https://img.shields.io/badge/Personas-7-purple?style=for-the-badge)](#personas)
[![Commands](https://img.shields.io/badge/Commands-131-orange?style=for-the-badge)](#commands)
[![Commands](https://img.shields.io/badge/Commands-138-orange?style=for-the-badge)](#commands)
[![Stars](https://img.shields.io/github/stars/alirezarezvani/claude-skills?style=for-the-badge)](https://github.com/alirezarezvani/claude-skills/stargazers)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1?style=for-the-badge)](https://getskillcheck.com)
@ -157,7 +157,7 @@ Run `./scripts/convert.sh --tool all` to generate tool-specific outputs locally.
| Domain | Skills | Highlights | Details |
|--------|--------|------------|---------|
| **🔧 Engineering — Core** | 53 | Architecture, frontend, backend, fullstack, QA, DevOps, SecOps, AI/ML, data, Playwright Pro (test gen, flaky fix, migrations), self-improving agent (auto-memory curation), security suite, a11y audit, **named-persona-adversarial-review** (review via named engineering philosophies), **embedded-iot-mentor** (MCU/board selection, firmware-reuse-first, breadboard-MVP discipline) | [engineering-team/](engineering-team/) |
| **⚡ Engineering — POWERFUL** | 90 | Agent designer, RAG architect, database designer, CI/CD builder, security auditor, MCP builder, AgentHub, Helm charts, Terraform, self-eval, llm-wiki, tc-tracker, autoresearch-agent, **reliability portfolio** (feature-flags-architect, kubernetes-operator, chaos-engineering, slo-architect), ship-gate, security-guidance PreToolUse hook, **Matt Pocock skills** (write-a-skill, caveman, grill-me, handoff, grill-with-docs), **zero-hallucination-coder** (Discuss→Map→Decompose→Execute→Verify), **agent-harness** (goal→plan→execute→verify→close loops over any domain), **memory-engineering** (price the memory write path, pick which cost to pay, audit FACT/SKILL/LOG density, gate on a forgetting policy), **skillopt-sleep** (nightly gated self-evolution from real Claude Code sessions, vendored from microsoft/SkillOpt), **book-to-skill** (compile a book, docs folder, or spec collection into a knowledge-base skill, then package it as a plugin), **boost-asio-pro** (async C++ networking — version-gated coroutine/callback styles, strand discipline), **human-gate** (batched human review as a structured artifact + a gate that refuses to close on open blockers), **agent-memory** (four-tier L0-L3 memory ladder over Claude Code hooks; promotion earned by recurrence across sessions and days, redacted or contested claims refuse to promote, nothing reaches CLAUDE.md without a human adopt), **skill-doctor** (grade the agent setup from real session history — rubric-judged, deterministically gated, evidence-traced skill edits) | [engineering/](engineering/) |
| **⚡ Engineering — POWERFUL** | 91 | Agent designer, RAG architect, database designer, CI/CD builder, security auditor, MCP builder, AgentHub, Helm charts, Terraform, self-eval, llm-wiki, tc-tracker, autoresearch-agent, **reliability portfolio** (feature-flags-architect, kubernetes-operator, chaos-engineering, slo-architect), ship-gate, security-guidance PreToolUse hook, **Matt Pocock skills** (write-a-skill, caveman, grill-me, handoff, grill-with-docs), **zero-hallucination-coder** (Discuss→Map→Decompose→Execute→Verify), **agent-harness** (goal→plan→execute→verify→close loops over any domain), **memory-engineering** (price the memory write path, pick which cost to pay, audit FACT/SKILL/LOG density, gate on a forgetting policy), **skillopt-sleep** (nightly gated self-evolution from real Claude Code sessions, vendored from microsoft/SkillOpt), **book-to-skill** (compile a book, docs folder, or spec collection into a knowledge-base skill, then package it as a plugin), **boost-asio-pro** (async C++ networking — version-gated coroutine/callback styles, strand discipline), **human-gate** (batched human review as a structured artifact + a gate that refuses to close on open blockers), **agent-memory** (four-tier L0-L3 memory ladder over Claude Code hooks; promotion earned by recurrence across sessions and days, redacted or contested claims refuse to promote, nothing reaches CLAUDE.md without a human adopt), **skill-doctor** (grade the agent setup from real session history — rubric-judged, deterministically gated, evidence-traced skill edits) | [engineering/](engineering/) |
| **🎯 Product** | 17 | Product manager, agile PO, strategist, UX researcher, UI design, landing pages, SaaS scaffolder, analytics, experiment designer, discovery, roadmap communicator, code-to-prd, apple-hig-expert | [product-team/](product-team/) |
| **📣 Marketing** | 49 | 8 pods: Content, SEO + AEO (`aeo` — E-E-A-T audit, citation tracking across 5 LLMs) + local (`local-seo-manager` — GBP/NAP/Map-Pack), CRO, Channels, Growth, Intelligence, Sales + `business-name-fit` (cross-cultural naming) + context foundation + orchestration router | [marketing-skill/](marketing-skill/) |
| **🚀 Productivity** | 12 | `capture` (brain-dump-to-action), `email` pair (inbox-setup + inbox-triage), `reflect` (journal), `handoff` (Matt Pocock-inspired), `andreessen` (market-first decision mode), `roast` (5-angle idea panel → GO/RESHAPE/KILL), `fable-goal` (ramble → autonomous /goal prompt), `weekly-review` (GTD loop with refusal gate), `deep-work` (time-blocking + shallow-work budget), `meetings` (cost gate + agenda + action items), `swedish-mentor` (CEFR-leveled Swedish learning paths) | [productivity/](productivity/) |

View file

@ -0,0 +1,70 @@
---
title: "Memory Curator — AI Coding Agent & Codex Skill"
description: "Curates the tiered agent-memory store. Use when reviewing what the agent has learned from past sessions, adopting staged promotions into CLAUDE.md. Agent-native orchestrator for Claude Code, Codex, Gemini CLI."
---
# Memory Curator
<div class="page-meta" markdown>
<span class="meta-badge">:material-robot: Agent</span>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agent-memory/agents/cs-memory-curator.md">Source</a></span>
</div>
You maintain a promotion ladder, not a database. Your bias is **refusal**: a
claim that stays at L1 costs the user one restatement; a wrong claim promoted to
always-loaded context costs them every future session until someone hunts down
where it came from.
## Your posture
**You are the human's instrument at the gate, not a replacement for them.** The
whole design rests on a person reviewing staged promotions. If you start
adopting things because they look fine, the security argument behind the whole
system collapses. Present, recommend, and wait.
Say what the evidence is, not what you think of the claim:
> "`PR base branch is dev` — 4 observations across 3 sessions, spanning 5 days,
> first seen in sessA.jsonl#L1. No contradiction open. Eligible for L2."
Not: "This looks like a good rule to remember."
## What you do
| Ask | You run |
|---|---|
| "what does it remember?" | `memory_inspect.py --tier L2` and `--tier L3` |
| "why does it think that?" | `memory_inspect.py --why "<claim>"` |
| "what's stuck?" | `memory_inspect.py --tier L1` — read the blocking reason on each |
| "what's disputed?" | `memory_inspect.py --contested` |
| "what's waiting?" | read `.memory/staged/promotions.json` |
| "adopt it" | walk the staged list one item at a time, then back up both `CLAUDE.md` files before writing |
## Hard rules
1. **Never adopt a redacted claim.** Not with more evidence, not with the user
saying it's fine in passing. The flag means the text was altered because it
looked like a secret, and the target file is committed to git. If the user
wants the underlying fact remembered, have them restate it in a form that
contains no secret — that restatement is a clean observation.
2. **Never adopt an atom whose citation does not resolve.** If `--why` reports
`ambiguous`, say so and stop: a wrong citation is worse than a missing one.
3. **Never resolve a contradiction yourself.** Present both claims, both dates,
both sources. The user picks.
4. **Back up before writing.** Both `CLAUDE.md` files, every time, before any
adopt.
5. **Never edit `.memory/atoms.jsonl` by hand to make something promotable.**
That is forging evidence. If a gate is wrong, change the gate in the open.
6. **Say when the store is thin.** Rule-based extraction has deliberately low
recall. If two weeks produce almost nothing, the honest report is "this is
not earning its keep — consider removing it," not a search for a looser
threshold.
## What you do not do
You do not summarize, rewrite, or "clean up" a claim's wording during adopt. The
wording *is* the evidence; changing it breaks the link to the transcript line
that produced it. If the wording is bad, reject it and let the user state the
rule properly — which becomes a new, better atom.

View file

@ -0,0 +1,63 @@
---
title: "Skill Doctor — AI Coding Agent & Codex Skill"
description: "Use when someone wants their agent setup graded from real conversation history, asks which of their installed skills actually fire, wonders whether. Agent-native orchestrator for Claude Code, Codex, Gemini CLI."
---
# Skill Doctor
<div class="page-meta" markdown>
<span class="meta-badge">:material-robot: Agent</span>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/agents/cs-skill-doctor.md">Source</a></span>
</div>
You are the skill doctor. You do not review skills by reading them — you review
them by reading **what happened when they ran**. The last 45 days of session
history are the only honest benchmark of an agent setup.
## Voice
Clinical and evidence-first. You never say a skill is "probably fine" — you say
how many sessions it fired in, and what it cost when it didn't. You are as proud
of filing zero suggestions as ten: a speculative edit to another agent's
instructions is malpractice, not initiative.
Your opening move on almost any request:
> "Before I read a single SKILL.md — let's see what your sessions say actually
> happened."
## Hard rules
1. **Local only, always.** Never upload a transcript, session file, or excerpt
of one. The scratch dir is the report's whole world; the user decides what
leaves it.
2. **Labels, never numbers.** You judge each transcript against the closed label
tables in `scorers/`. `score_aggregator.py` owns every number; if it exits 4,
fix what it names — never hand-edit `report.json` around it.
3. **No evidence, no suggestion.** Every proposed edit cites the sampled session
that motivated it. "Best practice says" is not a citation; drop it.
4. **Zero suggestions is a finding, not a failure.** When nothing clears the
filing bar in the skill's `skill_edit_governance.md` reference, say so per
finding.
5. **Proposed edits stay proposed.** They live under `$RUN/proposed/`; the user's
real skill files change only on an explicit per-skill yes.
6. **A never-firing installed skill is a description problem first.** Suggest the
trigger fix before any body edit.
7. **Report the redaction count.** If secrets were scrubbed from transcripts,
that is itself a finding about the workflow.
## Workflow
Load `engineering/skill-doctor/skills/skill-doctor/SKILL.md` and follow its five
steps: collect → score → draft → aggregate (the gate) → render. End every
engagement with the grade, the top findings in plain text, and the
`file://` link to the local report.
## Routing
- User wants a *nightly automated* self-improvement loop → `engineering/skillopt-sleep`.
- User wants to *author a new skill* from expertise in their head → `engineering/write-a-skill`.
- User wants this *session's own work* graded → `engineering-team` self-eval.
- User wants the repo's skills *statically* audited (no session history) → `/plugin-audit` or `scripts/audit_skills.py`.

View file

@ -1,13 +1,13 @@
---
title: "AI Coding Agents — Agent-Native Orchestrators & Codex Skills"
description: "96 agent-native orchestrators for Claude Code, Codex CLI, and Gemini CLI — multi-skill AI agents across engineering, product, marketing, and more."
description: "98 agent-native orchestrators for Claude Code, Codex CLI, and Gemini CLI — multi-skill AI agents across engineering, product, marketing, and more."
---
<div class="domain-header" markdown>
# :material-robot: Agents
<p class="domain-count">96 agents that orchestrate skills across domains</p>
<p class="domain-count">98 agents that orchestrate skills across domains</p>
</div>
@ -253,6 +253,12 @@ description: "96 agent-native orchestrators for Claude Code, Codex CLI, and Gemi
Engineering - POWERFUL
- :material-rocket-launch:{ .lg .middle } **[Memory Curator](cs-memory-curator.md)**
---
Engineering - POWERFUL
- :material-rocket-launch:{ .lg .middle } **[Hub Coordinator Agent](hub-coordinator.md)**
---
@ -337,6 +343,12 @@ description: "96 agent-native orchestrators for Claude Code, Codex CLI, and Gemi
Engineering - POWERFUL
- :material-rocket-launch:{ .lg .middle } **[Skill Doctor](cs-skill-doctor.md)**
---
Engineering - POWERFUL
- :material-rocket-launch:{ .lg .middle } **[Scraping Architect](cs-scraping-architect.md)**
---

107
docs/commands/cs-memory.md Normal file
View file

@ -0,0 +1,107 @@
---
title: "/cs-memory — Slash Command for AI Coding Agents"
description: "Inspect, trace, and adopt the tiered agent-memory store (status | why | contested | adopt | forget). Slash command for Claude Code, Codex CLI, Gemini CLI."
---
# /cs-memory
<div class="page-meta" markdown>
<span class="meta-badge">:material-console: Slash Command</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/2-claude-skills/tree/main/engineering/agent-memory/commands/cs-memory.md">Source</a></span>
</div>
Argument: `$ARGUMENTS` (default: `status`)
Scripts live at
`engineering/agent-memory/skills/agent-memory/scripts/`. All are stdlib-only and
read-only except where stated.
---
## `status` (default)
1. Run `memory_inspect.py --tier L3`, `--tier L2`, `--tier L1`.
2. Read `.memory/staged/promotions.json` if it exists.
3. Read the last 7 days of `.memory/errors.log` if it exists — **surface any
entry**. That file is where silently dropped writes are recorded, and a log
nobody is pointed at is the same as no log.
Report, in this order: what is always loaded (L3), what this project loads (L2),
how many candidates are waiting and what is blocking each, what is staged for
adoption, and any dropped writes.
**Do not adopt anything here.** `status` is read-only.
---
## `why "<claim>"`
Run `memory_inspect.py --why "<claim>"`.
Report the full provenance: observation count, distinct sessions, distinct
calendar days, first and latest transcript back-pointers, whether each resolves,
and the quoted source line when exactly one transcript matched.
If the resolution status is **`ambiguous`**, say so plainly and print no source
line. Two projects can hold a transcript of the same basename; guessing attaches
a real claim to the wrong session, and a wrong citation is worse than none.
---
## `contested`
Run `memory_inspect.py --contested`.
For each pair, present both claims with their dates and sources side by side and
ask the user which governs. **Do not pick.** Do not merge them. Do not mark one
resolved on your own judgement — resolution is a human decision by design.
---
## `adopt`
The only command in this file that writes. Six steps, in order, no skipping:
1. Run `memory_promote.py --stage` to refresh `.memory/staged/promotions.json`.
2. **Back up both `CLAUDE.md` files** (project and global) with a timestamped
copy. Do this before writing anything, every time.
3. Walk the staged list **one atom at a time**. For each, show the claim, the
evidence (sessions, days, sources), and the target file. Wait for the user.
4. **Refuse outright** any atom with `redacted: true` — no amount of evidence
substitutes for the human reading the original. Explain why and move on.
5. **Refuse** any atom whose citation does not resolve.
6. Append accepted atoms to the target `CLAUDE.md` under a clearly marked
`<!-- agent-memory: adopted -->` section, and log each to `.memory/adopted.log`.
Never write to a `CLAUDE.md` outside this flow. Never batch-accept.
---
## `forget "<claim>"`
1. Locate the atom with `memory_inspect.py --why "<claim>"`.
2. Show the user exactly what will be removed, from which tier, and whether it
was already adopted into a `CLAUDE.md`.
3. On confirmation, remove it from `.memory/atoms.jsonl` and, if it was adopted,
remove the corresponding line from the `CLAUDE.md` — after backing that file
up.
Removing an atom does **not** prevent re-learning. If the marker fires again in
a future session, it returns. That is correct: forgetting is not a permanent
veto, and saying so avoids a confusing surprise later. To stop it returning,
change the underlying fact or state the correction — a correction is itself a
high-confidence observation.
---
## Refuse and route
- No `.memory/` directory yet → say so. It is created on the first session end
with the hooks installed; nothing is wrong.
- User asks to lower a promotion threshold so something passes → refuse. Gates
are changed in the open, in `DESIGN.md`, not per-claim. Offer to record the
case as evidence the threshold is wrong.
- User asks to design or price a memory system generally → route to
`engineering/memory-engineering`. This skill *is* a memory system; that one
audits any of them, this one included.

View file

@ -0,0 +1,51 @@
---
title: "/cs-skill-doctor — Slash Command for AI Coding Agents"
description: "Grade the agent setup from real local session history — rubric-scored, evidence-gated, rendered as one local shareable report.. Slash command for Claude Code, Codex CLI, Gemini CLI."
---
# /cs-skill-doctor
<div class="page-meta" markdown>
<span class="meta-badge">:material-console: Slash Command</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/2-claude-skills/tree/main/engineering/skill-doctor/commands/cs-skill-doctor.md">Source</a></span>
</div>
Run the skill-doctor pass with `$ARGUMENTS` (pass any `--repo`, `--days`,
`--harness`, `--include-subagents` flags through to the collector).
Load `engineering/skill-doctor/skills/skill-doctor/SKILL.md` and follow it
exactly. Summary of the contract:
## Pre-flight
1. **Confirm the target repo** — the report is scoped to one repo's skills and
the sessions that ran inside it. Run from that repo or pass `--repo`.
2. **State the privacy contract up front**: everything runs locally, transcripts
are redacted before they touch disk, nothing is uploaded.
3. Create the scratch dir: `RUN="$(mktemp -d "${TMPDIR:-/tmp}/skill-doctor-XXXXXXXX")"`.
## Pipeline
```bash
python engineering/skill-doctor/skills/skill-doctor/scripts/collect_sessions.py --out "$RUN" $ARGUMENTS
python engineering/skill-doctor/skills/skill-doctor/scripts/score_aggregator.py --inventory "$RUN/inventory.json" --emit-template > "$RUN/session_scores.json"
# ... judge each transcript against scorers/, fill the template, draft suggestions ...
python engineering/skill-doctor/skills/skill-doctor/scripts/score_aggregator.py --inventory "$RUN/inventory.json" --scores "$RUN/session_scores.json" --suggestions "$RUN/suggestions.json"
python engineering/skill-doctor/skills/skill-doctor/scripts/render_report.py --report "$RUN/report.json"
```
If `sessions_sampled` is 0, stop and tell the user (suggest `--days 90`). If the
aggregator exits 4, fix what it names and re-run — never bypass it. Report every
non-zero exit code as a finding, not an error to swallow.
## Output
Tell the user, in text: the letter grade, the three top findings, how many
secrets were redacted, and the suggestion count (zero is a valid success — say
why per finding). Then link the local report:
- Your quality report: `file://$RUN/report.html` (print to PDF to share)
Finally ask: **"Want me to apply any of these proposed diffs to your real
skills?"** — and apply only on an explicit per-skill yes.

View file

@ -1,13 +1,13 @@
---
title: "Slash Commands — AI Coding Agent Commands & Codex Shortcuts"
description: "122 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
description: "124 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
---
<div class="domain-header" markdown>
# :material-console: Slash Commands
<p class="domain-count">122 commands for quick access to common operations</p>
<p class="domain-count">124 commands for quick access to common operations</p>
</div>
@ -253,6 +253,12 @@ description: "122 slash commands for Claude Code, Codex CLI, and Gemini CLI —
Parse $ARGUMENTS: the first token is the domain (one of the 18 manifest names under
- :material-console:{ .lg .middle } **[`/cs-memory`](cs-memory.md)**
---
Argument: $ARGUMENTS (default: status)
- :material-console:{ .lg .middle } **[`/cs-book-to-plugin`](cs-book-to-plugin.md)**
---
@ -313,6 +319,12 @@ description: "122 slash commands for Claude Code, Codex CLI, and Gemini CLI —
Run the memory-engineering pass on $ARGUMENTS.
- :material-console:{ .lg .middle } **[`/cs-skill-doctor`](cs-skill-doctor.md)**
---
Run the skill-doctor pass with $ARGUMENTS (pass any --repo, --days,
- :material-console:{ .lg .middle } **[`/skillopt-sleep`](skillopt-sleep.md)**
---

View file

@ -1,6 +1,6 @@
---
title: Agent Skills & Plugins for Claude Code, Codex, Gemini CLI & 10 More AI Tools
description: "345 production-ready agent skills, 78 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies."
description: "380 production-ready agent skills, 96 installable plugins, and 138 slash commands across 20 domains — engineering, product, marketing, compliance, finance, research, and agent tooling. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies."
hide:
- toc
- edit

View file

@ -22,7 +22,7 @@ a workflow**. Heavy intake stays in the forked context; the parent gets a digest
Inspired by Anthropic's `launch-your-agent` reference skill (Apache-2.0). This is
an independent re-implementation; CMA semantics come from
[`references/cma-primitives.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md).
[[`references/cma-primitives.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md).
## The through-line: the session goal
@ -36,7 +36,7 @@ the phase + recurrence selects the loop shape.
Run the router, then act on its exit code:
```bash
python3 skills/agent-launcher-orchestrator/scripts/goal_router.py --out-dir ./my-agent
python3 scripts/goal_router.py --out-dir ./my-agent
# exit 0 ROUTE -> fork to the named phase sub-skill
# exit 3 ASK -> ask the one printed forcing question, then re-route
# exit 4 REFUSE -> goal too vague; get one sentence, then re-route
@ -53,13 +53,13 @@ python3 skills/agent-launcher-orchestrator/scripts/goal_router.py --out-dir ./my
## Compile the loop
```bash
python3 skills/agent-launcher-orchestrator/scripts/loop_compiler.py \
python3 scripts/loop_compiler.py \
--out-dir ./my-agent --max-iterations 5 --cron "0 9 * * *" --timezone Europe/Berlin --nest-outcome
```
`loop_compiler.py` emits `plan.v1`: `single-pass`, `grade-iterate` (always with a
`max_iterations` cap 1..20), or `cron-loop` (optionally nesting a self-grading
outcome per firing). See [`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md).
outcome per firing). See [[`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md).
## Pre-flight gates (hard refusals)

View file

@ -20,15 +20,15 @@ This is the plugin's **loop**: CMA's `outcome` primitive self-grades the agent's
work in an isolated context and feeds failing verdicts back for the next attempt.
It is **always bounded** by `max_iterations` (1..20) — never "improve forever".
See [`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md)
See [[`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md)
and the outcome section of
[`references/cma-primitives.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md).
[[`references/cma-primitives.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/cma-primitives.md).
## Workflow
1. **Define the outcome.**
```bash
python3 skills/grade-iterate/scripts/outcome_builder.py \
python3 scripts/outcome_builder.py \
--sheet ./my-agent/build-sheet.json --max-iterations 5 \
--out ./my-agent/payloads/outcome.json
```
@ -36,7 +36,7 @@ and the outcome section of
payload as a `user.define_outcome` event (append to the running session).
2. **Read every verdict first.**
```bash
python3 skills/grade-iterate/scripts/verdict_reader.py --result ./my-agent/last-verdict.json
python3 scripts/verdict_reader.py --result ./my-agent/last-verdict.json
```
Tables the rubric outcome and recommends: **SHIP** (`satisfied`), **SHARPEN**
then re-run (`needs_revision`), **ESCALATE** (`max_iterations_reached` /
@ -46,7 +46,7 @@ and the outcome section of
run halts at the cap and escalates. Don't burn the budget on cosmetic edits.
4. **Once a version passes, run held-back eval.**
```bash
python3 skills/grade-iterate/scripts/eval_scaffold.py \
python3 scripts/eval_scaffold.py \
--sheet ./my-agent/build-sheet.json --out ./my-agent/eval.json --concurrency 5
```
Held-back cases (never seen during iteration) run in parallel, capped at the

View file

@ -17,7 +17,7 @@ description: "Phase 1 of building a Claude Managed Agent — interview the found
Open warmly with one or two examples from
[`references/examples-bank.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/examples-bank.md), then interview
[[`references/examples-bank.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/examples-bank.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/examples-bank.md), then interview
the founder into a **build sheet**. No API key needed in this phase — the output
is a plan.
@ -32,7 +32,7 @@ is a plan.
| **Done** | "How would you grade a good run?" | outcome `rubric` (required) |
| **Recurrence** | "Once, on request, or on a cadence?" | single-pass / grade-loop / cron-loop |
See [`references/interview-to-config.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/interview-to-config.md)
See [[`references/interview-to-config.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/interview-to-config.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/interview-to-config.md)
for the full mapping.
## Workflow
@ -41,7 +41,7 @@ for the full mapping.
invent specifics they didn't claim.
2. **Map to primitives.**
```bash
python3 skills/interview/scripts/interview_planner.py \
python3 scripts/interview_planner.py \
--job "Triage overnight support email" --trigger schedule \
--inputs "gmail,memory" --actions "label,reply" \
--dod "one label per email, grounded reason, no invented facts" \
@ -52,11 +52,11 @@ for the full mapping.
deferrals** behind `always_ask`.
3. **Assemble the sheet.**
```bash
python3 skills/interview/scripts/build_sheet_builder.py --plan ./my-agent/plan.json --out-dir ./my-agent
python3 scripts/build_sheet_builder.py --plan ./my-agent/plan.json --out-dir ./my-agent
```
4. **Validate limits.**
```bash
python3 skills/interview/scripts/primitives_validator.py --sheet ./my-agent/build-sheet.json
python3 scripts/primitives_validator.py --sheet ./my-agent/build-sheet.json
```
FAIL blocks progress; fix and re-run. WARN is advisory (surface it).
5. **Record the plan in the goal.** `goal_state.py set --phase stage-launch

View file

@ -20,7 +20,7 @@ A **scheduled deployment** fires a fresh session on a cron cadence — the agent
runs without you. Each firing can carry its own outcome, nesting the bounded
grade→iterate loop inside every recurring run.
See [`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md).
See [[`references/loops-and-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md)](https://github.com/alirezarezvani/claude-skills/tree/main/agent-launcher/references/loops-and-workflows.md).
## Choose the trigger
@ -34,14 +34,14 @@ See [`references/loops-and-workflows.md`](https://github.com/alirezarezvani/clau
1. **Validate the schedule.**
```bash
python3 skills/run-without-you/scripts/cron_validator.py --cron "0 9 * * *" --timezone Europe/Berlin
python3 scripts/cron_validator.py --cron "0 9 * * *" --timezone Europe/Berlin
```
Invalid cron/timezone → exit 1. Read the **DST note**: wall-clock semantics mean
spring-forward times are skipped and fall-back times fire twice — avoid
02:0003:00 in DST zones if exactly-once matters.
2. **Build the deployment payload.**
```bash
python3 skills/run-without-you/scripts/deployment_builder.py \
python3 scripts/deployment_builder.py \
--sheet ./my-agent/build-sheet.json --agent-id agent_123 --env-id env_456 \
--nest-outcome --out ./my-agent/payloads/deployment.json
```
@ -52,7 +52,7 @@ See [`references/loops-and-workflows.md`](https://github.com/alirezarezvani/clau
leave the cron in place. Pin the agent version in the deployment once it passes.
4. **Finalize the roadmap.**
```bash
python3 skills/run-without-you/scripts/next_directions_writer.py \
python3 scripts/next_directions_writer.py \
--sheet ./my-agent/build-sheet.json --loop-shape cron-loop --last-verdict satisfied --out-dir ./my-agent
```
5. **Advance + hand to wrap-up.** `goal_state.py set --phase wrap-up`, then invoke

View file

@ -24,7 +24,7 @@ their own key. **No script here touches the network or the key** — the user ru
1. **Generate payloads.**
```bash
python3 skills/stage-launch/scripts/payload_generator.py \
python3 scripts/payload_generator.py \
--sheet ./my-agent/build-sheet.json --out-dir ./my-agent
# -> ./my-agent/payloads/{01-environment,02-agent,03-session,04-kickoff}.json
```
@ -32,14 +32,14 @@ their own key. **No script here touches the network or the key** — the user ru
the agent payload's `permission_policies`).
2. **Write the launch script.**
```bash
python3 skills/stage-launch/scripts/launch_script_writer.py --out-dir ./my-agent
python3 scripts/launch_script_writer.py --out-dir ./my-agent
```
`launch.sh` creates environment → agent → session → kickoff **in order**,
chaining IDs, and **resumes** on re-run (each step skips if its `*.id` file
exists). It reads `$ANTHROPIC_API_KEY` at runtime.
3. **Validate before launch.**
```bash
python3 skills/stage-launch/scripts/payload_validator.py --dir ./my-agent
python3 scripts/payload_validator.py --dir ./my-agent
```
FAIL blocks — especially a `key_leak` finding. Fix and re-run.
4. **Minimal key step (never in chat).** Check the shell first:

View file

@ -24,14 +24,14 @@ and name the next 12 upgrades so the founder leaves with a clear roadmap. The
1. **Inventory what they own.**
```bash
python3 skills/wrap-up/scripts/primitives_inventory.py \
python3 scripts/primitives_inventory.py \
--sheet ./my-agent/build-sheet.json --goal ./my-agent/goal.json
```
Tables agent / environment / session / memory / outcome / deployment and the
phases completed.
2. **Regenerate the overview page.**
```bash
python3 skills/wrap-up/scripts/overview_page.py \
python3 scripts/overview_page.py \
--sheet ./my-agent/build-sheet.json --out-dir ./my-agent \
--status live --loop-shape cron-loop --last-verdict satisfied
```
@ -39,7 +39,7 @@ and name the next 12 upgrades so the founder leaves with a clear roadmap. The
assets) — shareable as-is.
3. **Suggest the next moves.**
```bash
python3 skills/wrap-up/scripts/upgrade_suggester.py --sheet ./my-agent/build-sheet.json --top 2
python3 scripts/upgrade_suggester.py --sheet ./my-agent/build-sheet.json --top 2
```
Ranks recorded deferrals (v1 before v2, real-integration first) plus standing
hardening (tighten networking, pin the agent version, nest an outcome).

View file

@ -26,6 +26,15 @@ Environment variables must be set:
If not set, inform the user how to get them from [browserstack.com/accounts/settings](https://www.browserstack.com/accounts/settings) and stop.
> **The BrowserStack MCP server is not auto-registered (issue #978).**
> `pw-browserstack` was removed from the plugin's `.mcp.json` because it failed to
> connect for every user (the plugin ships no `node_modules`). The `browserstack_*`
> MCP tools used below, and the `/pw:browserstack` command, will fail with "tool
> not found" until it is enabled manually — see the **Integrations** section of the
> plugin's `CLAUDE.md` (`cd integrations/browserstack-mcp && npm install`, then
> register the server in your own user/project MCP config). Setting the env vars
> alone is not sufficient.
## Capabilities
### 1. Configure for BrowserStack

View file

@ -102,13 +102,20 @@ npx playwright test tests/auth/login.spec.ts --headed
- **9 skills** with detailed step-by-step instructions
- **3 specialized agents**: test-architect, test-debugger, migration-planner
- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations
- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations *(optional — not auto-registered; see Integration Setup)*
- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects
- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
- **Migration guides**: Cypress and Selenium mapping tables
## Integration Setup
> **Not auto-registered (issue #978).** The TestRail and BrowserStack MCP servers
> are no longer declared in the plugin's `.mcp.json` (they failed to connect for
> every user — no bundled `node_modules`). Exporting the env vars below is not
> enough: `/pw:testrail` / `/pw:browserstack` fail with "tool not found" until you
> enable the server manually (`cd integrations/<name>-mcp && npm install`, then
> register it in your own user/project MCP config). See `CLAUDE.md` → Integrations.
### TestRail (Optional)
```bash
export TESTRAIL_URL="https://your-instance.testrail.io"

View file

@ -27,6 +27,14 @@ Environment variables must be set:
If not set, inform the user how to configure them and stop.
> **The TestRail MCP server is not auto-registered (issue #978).** `pw-testrail`
> was removed from the plugin's `.mcp.json` because it failed to connect for every
> user (the plugin ships no `node_modules`). The `testrail_*` MCP tools used below,
> and the `/pw:testrail` command, will fail with "tool not found" until it is
> enabled manually — see the **Integrations** section of the plugin's `CLAUDE.md`
> (`cd integrations/testrail-mcp && npm install`, then register the server in your
> own user/project MCP config). Setting the env vars alone is not sufficient.
## Capabilities
### 1. Import Test Cases → Generate Playwright Tests

View file

@ -0,0 +1,105 @@
---
title: "Agent Memory — promotion is earned, not asserted — Agent Skill for Codex & OpenClaw"
description: "Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead — or when. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw."
---
# Agent Memory — promotion is earned, not asserted
<div class="page-meta" markdown>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-identifier: `agent-memory`</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agent-memory/skills/agent-memory/SKILL.md">Source</a></span>
</div>
<div class="install-banner" markdown>
<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code>
</div>
> **Portability:** stdlib only. No database, no embeddings, no network, no LLM calls.
## The problem
A project's `CLAUDE.md` is a memory system with one tier and no eviction: every
durable fact and every passing preference land in the same always-loaded file,
until the important lines are diluted by the incidental ones. Facts learned
mid-session vanish at teardown unless someone writes them down.
**The fix is not more storage — it is a promotion ladder.** A claim earns its
way toward always-loaded context by recurring; a human confirms the last step.
## The four tiers
Tiers are distinguished by **injection policy**, not storage format.
| Tier | Holds | Injected | Committed |
|---|---|---|---|
| **L0** | raw session transcripts | never | no (already on disk) |
| **L1** | candidate atoms | on relevance, at prompt time | no (gitignored) |
| **L2** | this project's context | every session start | yes, after adopt |
| **L3** | stable cross-project persona | always | yes, after adopt |
## The gates
Nothing moves up because it sounded important. It moves up because it recurred.
- **L0 → L1** — an explicit marker fires (a directive, a correction, a stated
preference, a named lesson, a reproducible failure). Rule-based, high
precision, deliberately low recall.
- **L1 → L2** — ≥ 3 distinct sessions spanning ≥ 2 distinct calendar days. A
claim stated outright needs 2 sessions; the distinct-day rule still applies. A
verified claim promotes on one observation and is the only day-exempt path.
- **L2 → L3** — held in ≥ 2 distinct projects, aged ≥ 30 days, uncontested.
**Two gates refuse rather than guess.** A claim whose text was altered by
redaction never promotes on evidence alone — the flag firing is evidence the
source was sensitive, and a lexical filter finding one secret is not proof it
found all of them. A claim with an open contradiction is frozen at L1 until a
human resolves it; the incumbent is never silently overwritten.
## Use it
```bash
# what is remembered, and what is blocking the next promotion
python3 scripts/memory_inspect.py --tier L1
# where did this line come from — sessions, days, transcript, quoted source
python3 scripts/memory_inspect.py --why "PR base branch is dev"
# every claim with an open contradiction, both directions of the join
python3 scripts/memory_inspect.py --contested
# dry-run the promotion pass; writes nothing
python3 scripts/memory_promote.py
```
Three hooks run the loop unattended: `SessionStart` injects L2 + L3,
`UserPromptSubmit` recalls relevant L1 atoms, `SessionEnd` captures and stages.
Each is disabled independently with `AGENT_MEMORY_SESSIONSTART=0`,
`AGENT_MEMORY_USERPROMPTSUBMIT=0`, `AGENT_MEMORY_SESSIONEND=0`. Every hook fails
open: a broken memory system costs you memory, never a session.
## Hard rules
1. **Redact before writing.** Every atom passes the filter before it reaches
disk. Anything altered is quarantined from promotion.
2. **Propose, never apply.** Promotions land in `.memory/staged/`. Only an
explicit `/cs:memory adopt` touches a `CLAUDE.md`, and it backs both up first.
3. **Cite, don't invent.** Every atom carries a back-pointer to the transcript
line that produced it. `--why` resolving to *ambiguous* prints nothing rather
than guess: a wrong citation is worse than a missing one.
4. **Never surface a contested claim as fact.** It is still injected — hiding
the conflict is worse — but always tagged.
5. **The committed tiers carry no paths.** Promotion strips the back-pointer
prefix, which embeds an OS username.
## Forcing questions
Walk these one at a time before trusting the store.
1. Which line in your `CLAUDE.md` did you last actually read before acting?
2. Would you rather the agent forget a true thing, or remember a false one?
3. When two remembered rules disagree, who decides — and when?
4. What would make you delete `.memory/` entirely?
Rationale, open decisions, field schema: [[`agent-memory/DESIGN.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agent-memory/DESIGN.md)](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agent-memory/DESIGN.md).

View file

@ -0,0 +1,181 @@
---
title: "Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm — Agent Skill for Codex & OpenClaw"
description: "Orchestrate free opencode workers from Claude Code to cut token costs. Use when delegating grunt work to a single worker or a parallel swarm."
---
# Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm
<div class="page-meta" markdown>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-identifier: `hivemind`</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/hivemind/SKILL.md">Source</a></span>
</div>
<div class="install-banner" markdown>
<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code>
</div>
Claude Code = brain (plans, reviews, merges). opencode = disposable workers on free models
(`opencode/mimo-v2.5-free` default; verified $0.00 per run).
## Prerequisites (external dependency)
This skill is a thin orchestration layer over **[opencode](https://opencode.ai)**, a
third-party CLI. It is not bundled — install and authenticate it yourself first:
| Requirement | Notes |
|---|---|
| Node.js >= 18 | The scripts use `fetch` and `node:timers/promises`. |
| `opencode` CLI on `PATH` | `npm i -g opencode-ai` (or the installer opencode documents). |
| An authenticated opencode account | `opencode auth login`. Workers run as your account. |
| Default model `opencode/mimo-v2.5-free` | A free tier offered by opencode, not by Anthropic. Availability, rate limits, and pricing are opencode's to change — override with `--model` at any time. |
| Windows only: `OPENCODE_GIT_BASH_PATH` | Point at `C:\Program Files\Git\bin\bash.exe`, set persistently. |
Nothing here calls the Anthropic API on the worker side; worker traffic goes to
opencode's endpoints. Do not delegate secrets or private code you would not send there.
## Setup
1. Put this skill folder wherever your agent loads skills from (e.g. `~/.claude/skills/hivemind`).
2. Export `HIVEMIND_HOME` pointing at that folder — the bundled slash commands use it:
```
export HIVEMIND_HOME="$HOME/.claude/skills/hivemind"
```
3. Copy the bundled assets into place:
- `assets/commands/*.md` -> `~/.claude/commands/` (the `/hive`, `/oc`, `/swarm`, ... entry points)
- `assets/agents/*.md` -> `~/.config/opencode/agent/` (the scout / coder / tester worker personas)
Both copies are optional: everything the commands do can be driven by invoking
`scripts/oc-worker.mjs` directly, and any opencode agent name works with `--agent`.
Runtime state (`.runs/*.jsonl`) is written inside this folder and is gitignored.
## Components
| Path (relative to this skill dir) | Purpose |
|---|---|
| `scripts/oc-worker.mjs` | ONLY sanctioned way to invoke a worker. Hardened join point. |
| `scripts/oc-status.mjs` | Fleet progress from run logs (`oc-status.mjs <run-id>`) |
| `scripts/oc-aggregate.mjs` | Dedupe/synthesize N worker outputs; consensus findings first |
| `scripts/bench/run-bench.mjs` | Benchmark configs A (claude solo), B (opencode solo), C (orchestrated swarm) |
| `scripts/bench/grader-prompt.md` | Blind grading rubric (max 12 pts + PASS/FAIL gate) |
| `assets/commands/` | Slash-command entry points to copy into `~/.claude/commands/` |
| `assets/agents/` | scout / coder / tester agent definitions for opencode |
Slash commands (ship in `assets/commands/`, copy to `~/.claude/commands/`):
- `/hive <task>` - AUTO-ROUTER. Classifies task -> single worker, generic swarm, or template. Default entry point; prefer this over manual routing.
- `/oc <task>` - single worker delegation
- `/swarm <task>` - generic parallel swarm
- `/review-panel <diff>` - 4-lens parallel review (correctness/security/performance/style) + consensus aggregation
- `/research-sweep <question>` - 3-5 parallel research angles, synthesized
- `/migration <task>` - batched per-worktree migration workers + sequenced merge
- `/test-fleet <target>` - partitioned parallel test runs with safety checks
Worker agents (ship in `assets/agents/`, copy to `~/.config/opencode/agent/`):
- **scout** - read-only research (no write/edit/bash)
- **coder** - implements one subtask in its worktree
- **tester** - runs tests only, never edits source
## Invocation contract
```
node "<skill-dir>\scripts\oc-worker.mjs" [--agent scout|coder|tester] [--dir <path>] [--model <p/m>] [--timeout 900] [--run <id> --label <name>] "TASK TEXT"
```
Returns exactly ONE compact JSON line:
`{ ok, result, tokens:{total,input,output,cache}, cost_usd, duration_ms, label, agent, model }`
On failure: `{ ok:false, stage:"args"|"exec"|"api"|"parse"|"empty", error }` with stderr capped at 300 chars.
`--run <id>` + `--label <name>` append lifecycle events (start/done/fail) to `.runs/<id>.jsonl`
inside this skill dir. Use them for EVERY swarm worker so progress is recoverable via
`oc-status.mjs` even after orchestrator context loss.
The script auto-manages the shared server: health-checks `127.0.0.1:4096`, spawns `opencode serve` if dead, waits 5s, falls back to cold start. Workers are idempotent against their `--dir`; re-run once on `ok:false` before giving up.
`HIVEMIND_SERVER_URL` overrides that address (default `http://127.0.0.1:4096`). It must be a
valid URL with a numeric port; anything else fails fast with a single `stage:"args"` JSON line
rather than reaching the spawned process.
## Golden Rule (non-negotiable)
Raw opencode NDJSON streams must NEVER enter your context. All output arrives via the
script's single JSON line. Never pipe `opencode run --format json` directly into this
conversation; never re-implement what the script does.
## Single worker flow (/oc)
For one read-only question or small delegation: run oc-worker.mjs without worktrees.
Read-only tasks may omit `--agent`/`--dir`. Summarize `result` for the user.
If files were written: show `git diff` before letting the user commit.
## Swarm flow (multi-worker)
1. Decompose task into 2-5 INDEPENDENT subtasks (no shared files).
2. Writing workers get isolated worktrees FIRST: `git worktree add ../<repo>-wt-N -b swarm/N`.
3. Issue ALL worker invocations as PARALLEL Bash tool calls in ONE message.
4. Review every diff yourself (`git diff main...swarm/N`). YOU are the only merger.
5. Merge approved branches, remove worktrees, run tests.
6. Report table: subtask | agent | tokens | outcome + total worker tokens.
HARD RULES: workers never share directories; never delegate merging/reviewing;
escalate to your own Sonnet only when a free-model worker demonstrably fails twice.
## Benchmarking
```
node scripts\bench\run-bench.mjs --repo <project> [--configs a,b,c] [--task 1-5]
```
Appends JSONL records (ts, config, tokens, cost, duration) to `bench-results.jsonl`.
Grade artifacts blind with `grader-prompt.md` (grader sees only task spec + output).
Configs: A=claude solo baseline, B=opencode solo, C=claude orchestrating 2 workers.
## Fallback ladder (all flows)
1. Worker `ok:false` -> re-invoke once against the same dir.
2. Still failing -> orchestrator performs that subtask inline, marks it `[orchestrator-sourced]`.
3. opencode entirely down (`exec`/`api` twice) -> announce, abandon workers, do the task directly.
Never let a swarm fail a task that Claude could have done itself.
## Fleet patterns
Four reusable topologies ship as slash commands (see table above). Shared invariants:
parallel spawns in one message; `--run/--label` on every worker; aggregation via
`oc-aggregate.mjs` when 3+ workers produce findings; consensus beats single-lens claims;
worktree isolation whenever any worker writes.
## Windows notes (hard-won)
- Requires `OPENCODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe` (set persistently).
- The script resolves the REAL `opencode.exe` by parsing the npm `.cmd` shim — Node's
EINVAL policy blocks spawning `.cmd` directly. Do not "simplify" resolver back to
`where.exe` first-line.
- Free models: `opencode/mimo-v2.5-free`, `opencode/nemotron-3.5-lightning-free`,
`opencode/hy3-free`. NOTE: `opencode-go/*` models require workspace billing — avoid.
## Known limits
- Free-tier rate limits can 429 under heavy swarms; space out retries.
- Worker quality varies; always review diffs. Scout answers are evidence-cited.
- Bench config C consumes real Claude tokens for orchestration (~1-2k/task).
## Anti-patterns
| Anti-pattern | Why it breaks | Do this instead |
|---|---|---|
| Piping `opencode run --format json` straight into the orchestrator | Raw NDJSON floods context — the exact cost the skill exists to avoid | Always go through `scripts/oc-worker.mjs`, which returns one compact JSON line |
| Two writing workers in one directory | Concurrent edits corrupt each other's diffs | One git worktree per writing worker, created before the spawn |
| Letting a worker merge, review, or approve its own branch | Free-tier workers are the least reliable judges of their own output | The orchestrator is the only merger and the only reviewer |
| Spawning workers sequentially, one per message | Loses the entire wall-clock benefit of a swarm | Issue every worker invocation as parallel calls in ONE message |
| Retrying a failing worker indefinitely | Burns rate limit and stalls the task | Retry once, then do the subtask inline and mark it `[orchestrator-sourced]` |
| Delegating secrets, credentials, or private code | Worker traffic leaves for opencode's endpoints | Keep sensitive context in the orchestrator; send workers only what is safe to share |
| Trusting `cost_usd: 0` as a permanent guarantee | The free tier belongs to opencode and can change | Re-check pricing before relying on zero cost for bulk work |
## Cross-references
- `engineering/llm-cost-optimizer` — decide *whether* a task is worth delegating before Hivemind decides *how*
- `engineering/agent-harness` — harness patterns for the orchestrator side of the loop
- `engineering/workflow-builder` — for deterministic pipelines that do not need independent worker judgment
- `engineering/skills` and `engineering/write-a-skill` — authoring conventions used by the worker agent definitions in `assets/agents/`

View file

@ -1,13 +1,13 @@
---
title: "Engineering - POWERFUL Skills — Agent Skills & Codex Plugins"
description: "83 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
description: "86 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
---
<div class="domain-header" markdown>
# :material-rocket-launch: Engineering - POWERFUL
<p class="domain-count">83 skills in this domain</p>
<p class="domain-count">86 skills in this domain</p>
</div>
@ -131,6 +131,12 @@ description: "83 engineering - powerful skills — advanced agent-native skill a
Tier: POWERFUL
- **[Hivemind: Claude Code as Orchestrator, opencode as Free Worker Swarm](hivemind.md)**
---
Claude Code = brain (plans, reviews, merges). opencode = disposable workers on free models
- **[Interview System Designer](interview-system-designer.md)**
---

View file

@ -0,0 +1,96 @@
---
title: "skill-doctor — grade the agent setup from real sessions — Agent Skill for Codex & OpenClaw"
description: "Use when the user wants their agent setup graded from real conversation history, asks which installed skills are actually working, or wants."
---
# skill-doctor — grade the agent setup from real sessions
<div class="page-meta" markdown>
<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
<span class="meta-badge">:material-identifier: `skill-doctor`</span>
<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/SKILL.md">Source</a></span>
</div>
<div class="install-banner" markdown>
<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code>
</div>
> **Privacy is the contract.** Everything runs locally. Transcripts are condensed,
> secret-redacted, chmod-0600, and never uploaded — the only shareable artifact is
> the report the user chooses to share.
Run from the repo being graded. Every artifact goes to one fresh scratch dir, never
into the repo:
```bash
RUN="$(mktemp -d "${TMPDIR:-/tmp}/skill-doctor-XXXXXXXX")"
python scripts/collect_sessions.py --out "$RUN" # 1 — harvest + redact
```
**1 — Collect.** Scans Claude Code project-history JSONL and Codex rollouts,
discovers repo skills (`.claude/skills`, `.agents/skills`, `.codex/skills`, plugin
layouts), detects skill usage (`Skill` invocations, slash commands, SKILL.md paths), samples
newest-first, and writes redacted transcripts. Read `$RUN/inventory.json`: if
`sessions_sampled` is 0, tell the user there is nothing recent to score (suggest
`--days 90` or `--repo`) and stop. `skills_found` 0 is fine — the report becomes a
case for creating skills.
**2 — Score.** `python scripts/score_aggregator.py --inventory "$RUN/inventory.json"
--emit-template > "$RUN/session_scores.json"`. Read each transcript in
`$RUN/transcripts/` and judge it against **both** rubrics — `scorers/efficiency.md`
and `scorers/code-quality.md`. Fill the template with a **label from the rubric's
table** and a 13 sentence reason citing transcript specifics. Never invent numeric
scores — the aggregator derives them from labels. Use `insufficient_evidence` when
a transcript shows no judgeable diff. Also write 15 `top_findings`: the most
impactful cross-session patterns, concrete and specific.
**3 — Draft edits.** Follow `references/skill_edit_governance.md` (the filing bar:
would a competent agent with the current instructions still fail this way?). For
each suggestion that clears it, write the full improved SKILL.md to
`$RUN/proposed/<skill>/SKILL.md`, produce `diff -u <current> <proposed>`, and record
it in `$RUN/suggestions.json` citing the sampled session id(s) that motivated it.
Zero suggestions is a valid success — say why per finding. Never modify the user's
real skill files in this step.
**4 — Aggregate (the gate).** `python scripts/score_aggregator.py --inventory
"$RUN/inventory.json" --scores "$RUN/session_scores.json" --suggestions
"$RUN/suggestions.json"`. It validates labels against the rubric tables, refuses
scores for unsampled sessions, requires substantive reasons, rejects suggestions
that cite no scored session, computes `overall = 0.5·efficiency +
0.35·code_quality + 0.15·skill_coverage`, and writes `report.json`. **Exit 4 is a
stop**: fix what it names and re-run; never hand-edit report.json around it.
**5 — Render + tell.** `python scripts/render_report.py --report "$RUN/report.json"`
→ one self-contained `report.html` (no JS, no CDN, dark-mode + print-to-PDF). Then
tell the user the grade and the top findings in text, link
`file://$RUN/report.html`, and ask whether to apply the proposed diffs to their
real skills — apply only on an explicit yes, skill by skill.
## Hard rules
1. **Never upload transcripts, session files, or any excerpt.** Local only.
2. **Labels only, from the rubric tables.** The aggregator owns all arithmetic.
3. **Every suggestion traces to a scored session** — or it is dropped. Generic best practice is not evidence.
4. **Zero suggestions is a success**, not a failure to report around.
5. **Exit 4 from the aggregator is a stop**, not an error to swallow or bypass.
6. **Never touch the user's real skill files** without an explicit per-skill yes; proposed edits live under `$RUN/proposed/`.
7. **A proposed skill edit follows write-a-skill discipline** — trigger phrase in the description, smallest change that expresses the rule, replace over append.
## Scripts
| Script | Role | Exit codes |
|---|---|---|
| `scripts/collect_sessions.py` | Harvest Claude Code + Codex sessions, redact secrets, sample, inventory | 0 · 3 bad input |
| `scripts/score_aggregator.py` | Validate labels/reasons/suggestions, compute grade, emit report.json | 0 · 2 warnings · 3 bad input · 4 validation failure |
| `scripts/render_report.py` | report.json → single self-contained report.html | 0 · 3 bad input |
All support `--help`, `--output json`, and `--sample` (no real history needed).
## References and assets
- [`scorers/efficiency.md`](scorers/efficiency.md) · [`scorers/code-quality.md`](scorers/code-quality.md) — the two rubrics, preserved verbatim from upstream
- [`references/transcript_scoring_canon.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/references/transcript_scoring_canon.md) — why rubric-anchored LLM judging works and where it fails (7 sources)
- [`references/session_mining_privacy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/references/session_mining_privacy.md) — the local-only contract, redaction pattern canon (7 sources)
- [`references/skill_edit_governance.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/references/skill_edit_governance.md) — the filing bar for proposing skill edits (7 sources)
- [`assets/session_scores.example.json`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/assets/session_scores.example.json) · [`assets/suggestions.example.json`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/assets/suggestions.example.json) · [`assets/report.example.json`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skill-doctor/skills/skill-doctor/assets/report.example.json) — the three handoff shapes

View file

@ -1,4 +1,5 @@
---
name: hive-coder
description: Focused coder - implements exactly the assigned subtask in its worktree
mode: subagent
model: opencode/mimo-v2.5-free

View file

@ -1,4 +1,5 @@
---
name: hive-scout
description: Read-only codebase scout - research and reporting, zero writes
mode: subagent
model: opencode/mimo-v2.5-free

View file

@ -1,4 +1,5 @@
---
name: hive-tester
description: Test runner - executes tests and diagnoses failures, never edits source
mode: subagent
model: opencode/mimo-v2.5-free

View file

@ -1,6 +1,6 @@
site_name: Claude Code Skills & Agent Plugins
site_url: https://alirezarezvani.github.io/claude-skills/
site_description: "345 production-ready agent skills, 78 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies."
site_description: "380 production-ready agent skills, 96 installable plugins, and 138 slash commands across 20 domains — engineering, product, marketing, compliance, finance, research, and agent tooling. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies."
site_author: Alireza Rezvani
repo_url: https://github.com/alirezarezvani/claude-skills
repo_name: alirezarezvani/claude-skills