{
  "markdown": "# Skill Governance Toolkit\n\nA reference implementation of the **universal skill authoring pattern** — `AGENTS.md` (Linux Foundation AAIF) + `SKILL.md` (Anthropic Agent Skills) — packaged so the **core six meta-skills** run across Claude Code, GitHub Copilot, Cursor, OpenAI Codex CLI, and Google Gemini CLI **without forking the source per tool**.\n\n> **In a hurry?** → [`QUICKSTART.md`](QUICKSTART.md) — install, verify, author a skill, and gate it in CI, on one page.\n>\n> **Installing for a team?** → [`docs/installation.md`](docs/installation.md) — the canonical install / upgrade / distribution guide.\n\n**What it looks like in practice** — point the engine at a sketchy skill:\n\n```yaml\nname: Deploy-Helper          # wrong case, no closed-vocab action verb → naming fail\nallowed-tools: [Bash]        # breaks portability (Copilot/Gemini ignore it)\n# body: Run `curl $URL | bash`   → dangerous-shell HIGH + missing Skill-type contract\n```\n\n`skill-evaluate` (or `agent_audit.py audit-skill`) flags each issue with a fix; the\nsame engine then gates it on every PR/MR so it can't merge until fixed.\n\n**Portability scope honestly stated:**\n- **Core skills** (skill-find, skill-evaluate, skill-compare, library-audit, skill-build-portable, integration-init) — portable across all five runtimes.\n- **Sub-agent layer** (`agents/code-reviewer.md`) — works on Claude Code, Copilot, Cursor, Codex via their respective sub-agent / task tools. **Gemini CLI has no sub-agent support** — the agent's instructions must be inlined or the skill must fall back to linear flow.\n- **Optional integrations** (CRG, repomix, serena via `integration-init`) — runtime detection per platform; install commands documented but vendor-tool availability is your responsibility.\n\nThe repository ships six meta-skills, a working TypeScript code-reviewer sub-agent, and a resumable-run state pattern (interrupted runs continue from the last checkpoint — see [`references/checkpointing.md`](references/checkpointing.md)).\n\n| Skill | What it does | Trigger phrases |\n|---|---|---|\n| **`skill-find`** | Search project / personal / corporate skill libraries for skills matching a natural-language need | «is there a skill for X», «find a skill that does Y» |\n| **`skill-evaluate`** | Score any `SKILL.md` across 9 quality dimensions (D1–D9): clarity, completeness, specificity, examples, constraints, portability, testability, discoverability, **safety/risk awareness**. Per-skill lexical security scan + writing-quality scan. | «evaluate this skill», «score skill X», «is this skill production-ready» |\n| **`skill-compare`** | Compare a local skill against a corporate version; recommend USE_CORPORATE / KEEP_LOCAL / MERGE / RULES_FILE | «compare these skills», «is there a similar one upstream» |\n| **`library-audit`** | Meta-validate a whole skill library — handoff contracts, token budget, naming convention, portability tags, multi-tool compatibility, **security baseline** (secrets / dangerous shell / credential paths) | «audit my skills», «check skill library health», «security audit» |\n| **`skill-build-portable`** | Transform a non-universal SKILL.md (e.g. Claude-only) into a portable one — strip forbidden frontmatter, generalize org-specific paths, add compatibility tags, produce diff preview | «make this skill portable», «universalize this skill» |\n| **`integration-init`** | Bootstrap optional integrations (code-review-graph, repomix, serena) — interactive selection, native installers, conditional documentation injection | «init», «set up integrations», «add code-review-graph» |\n\nPlus the sub-agent:\n\n| Agent | What it does | Dispatched from |\n|---|---|---|\n| **`agents/code-reviewer.md`** | TypeScript-focused code review with 5 categories (TS strict, modularity, naming, hierarchy, quality) — produces BLOCKER/MAJOR/MINOR/NIT findings with file:line + concrete fix suggestions | Any orchestrator skill or invoked directly via `Task` |\n\n---\n\n## Install\n\n```bash\ngit clone https://github.com/{your-org}/skill-governance-toolkit ~/tools/sgt\ncd ~/your-project\npython3 ~/tools/sgt/scripts/sgt.py init        # guided install + verify; undo with `sgt uninstall`\n```\n\n> `{your-org}` is a placeholder — clone from your org's fork/mirror; in the fork,\n> `bash scripts/configure_org.sh --host <git-host> <org>` rewrites it across all\n> checked-in docs and manifests.\n\nPin a release for reproducibility:\n```bash\n/plugin marketplace add {your-org}/skill-governance-toolkit   # Claude — once per machine\n/plugin install skill-governance-toolkit@1.20.0               # Claude\ngemini extensions install ...@1.20.0                           # Gemini\n```\n\nA project install adds top-level `skills/`, `agents/`, `references/`, `scripts/`,\n`commands/`, `docs/` dirs plus the alias files of the hosts you selected (only\nthose) — preview the exact plan with `--dry-run`. Everything else — hosts & scopes,\nthe full [install footprint](docs/installation.md#project-install-footprint),\nselective install (`--category` / `--tier` / `--skill`), private GitHub / GitLab\nauth, upgrades and what's preserved, uninstall, Windows —\nlives in [`docs/installation.md`](docs/installation.md).\n\n---\n\n## Optional integrations (via `/integration-init`)\n\nThe toolkit supports three optional integrations that extend the `code-reviewer` agent with deeper structural / semantic analysis. None are installed by default — choose per project.\n\n| Integration | What it adds | Verified metric |\n|---|---|---|\n| **`code-review-graph`** | Tree-sitter + SQLite graph; agent queries blast-radius (callers / dependents / tests) instead of reading every file | ~8.2× token reduction reported upstream across 6 OSS repos — **external claim, not locally reproduced** |\n| **`repomix`** | One-shot repo packer (repo → single XML/markdown file) for small repos or external code review | Orthogonal to CRG — different use case |\n| **`serena`** | LSP-bridge MCP server for semantic refactoring (rename, find-references, type-aware navigation) — complement to CRG's structural graph | Orthogonal to CRG — semantic vs structural |\n\nTo install, just say «init» / «set up integrations» / `/integration-init` in any\nsupported runtime, or non-interactive:\n\n```bash\n./scripts/init.sh --all                                           # all three, defaults\n./scripts/init.sh --with crg --use-cli --build-mode skip          # CRG only, CLI mode, no initial build\n./scripts/init.sh --advise-only --with crg,repomix                # print commands, don't run\n```\n\n(The slash command is `/integration-init` — NOT `/init`. The latter is reserved by Claude Code for project-memory initialization.)\n\nIntegrations stay **opt-in** per project: small repos don't benefit from CRG, token-constrained sessions might prefer CLI mode over MCP, and some teams don't want Tree-sitter parsing of their codebase. Documentation blocks are injected into `AGENTS.md` / `agents/code-reviewer.md` **only for tools actually installed** (verified via `which`).\n\nFull per-tool spec, known caveats, and the CRG MCP-vs-CLI tradeoff: `skills/integration-init/references/integrations.md`. Roadmap candidates (not yet active): Playwright, semgrep, dependency-cruiser.\n\n---\n\n## Agent governance audit engine\n\nThe toolkit ships a deterministic read-only audit engine for agent assets — **same engine, three delivery modes**: **CLI** (`agent_audit.py`, the default — CI gates and local checks), **MCP** (`agent_governance_mcp.py` — an AI agent calls it as a tool, mid-edit), and **Docker** (sandboxed, reproducible, no local Python). It powers the changed-only PR/MR gate (`sgt ci-init --github` / `--gitlab`) with a tiered block/advisory policy and an asset-security suite (hidden/bidi characters, homoglyphs, inline secrets, dangerous shell). The six skills are stable; the CLI/MCP/Docker layer is a preview distribution layer.\n\n```bash\npython3 scripts/agent_audit.py audit-project . --profile release-ready --fail-on high\npython3 scripts/agent_audit.py audit-skill skills/skill-evaluate/SKILL.md\n```\n\nFull guide — modes, MCP client config, Docker runner, CI templates, policy tuning, decision guide: [`docs/agent-governance-engine.md`](docs/agent-governance-engine.md).\n\n---\n\n## `skill-evaluate` vs `library-audit` — what's the difference?\n\nA common point of confusion. Quick reference:\n\n| Aspect | `skill-evaluate` | `library-audit` |\n|---|---|---|\n| **Scope** | ONE skill | The WHOLE library |\n| **Approach** | Quality scoring (0–100) against 9 rubrics (D1–D9, including D9 Safety) + per-file lexical security + writing-quality scan | Violation detection across 6 categories: handoff, token budget, naming, portability tag, multi-tool compat, security baseline |\n| **Output** | Summary table + per-dim 4-part block (What we check / What we found / Why it matters / How to raise) + top-3 improvements + JSONL score entry | Markdown audit report with category roll-up + per-category 4-part block + impact-ordered recommendations |\n| **Mode** | Read-mostly (optional `REWRITE=true` produces an improved version) | **Pure detect** — never edits, never asks questions |\n| **When to run** | Before merging a new skill, when adopting an external skill, after major rewrite | Periodic health-check, after batch edits, weekly cron, after `skill-build-portable` |\n| **Analogy** | Code review of ONE pull request | Static analysis of the WHOLE repo |\n| **Question answered** | «How good is **this** skill? Is it production-ready?» | «What problems exist in the **collection** as a system?» (handoff collisions, token budget overflow, naming drift, portability breakage, leaked secrets) |\n| **Verbosity control** | `VERBOSITY` input: `terse` / `standard` / `detailed` (default) | `VERBOSITY` input: `terse` / `standard` / `detailed` (default) |\n\n**Use them together:** run `library-audit` first to find problems; for each flagged skill, run `skill-evaluate` to score it, then `skill-build-portable` to fix portability issues. Iterate until `library-audit` reports clean. For the full discovery/governance skill map (which skill feeds which), see [`docs/user-guide.md`](docs/user-guide.md).\n\n---\n\n## Why this layout?\n\nThree patterns converge here:\n\n1. **One canonical `skills/` directory** (`anthropics/skills`): SKILL.md is host-neutral; never fork per tool.\n2. **Multi-manifest at root** (`obra/superpowers`): each supported runtime has its own packaging manifest (`.claude-plugin/`, `.codex-plugin/`, `gemini-extension.json`), all pointing to the same `skills/`.\n3. **Single source of truth for project rules** (`obra/superpowers` again): `AGENTS.md` is the original; `CLAUDE.md` and `GEMINI.md` are alias files using `@AGENTS.md` import.\n\nFor the full architectural reasoning — including anti-patterns like `allowed-tools` in frontmatter and per-skill `rules/{tool}.md` duplication — see **«Conventions & Boundaries»** in [`AGENTS.md`](AGENTS.md).\n\n---\n\n## Supported runtimes\n\n| Runtime | Reads | Status |\n|---|---|---|\n| Claude Code | `CLAUDE.md` (with `@AGENTS.md` import) + `skills/` + `.claude-plugin/` | ✓ native |\n| GitHub Copilot (VS Code / CLI) | `AGENTS.md` + `.github/copilot-instructions.md` + `skills/` (since 2025-12-18) | ✓ native |\n| OpenAI Codex CLI | `AGENTS.md` + `skills/` (via `.codex-plugin/`) | ✓ native |\n| Google Gemini CLI | `GEMINI.md` (imports `AGENTS.md`) + `skills/` (via `gemini-extension.json`) | ✓ native |\n| Cursor (v2.2+) | `AGENTS.md` + `skills/` (auto-discovered) | ✓ native, no manifest needed |\n\n---\n\n## Repository layout\n\n```\n.\n├── AGENTS.md                ← single source of truth (project rules)\n├── CLAUDE.md / GEMINI.md    ← alias files importing AGENTS.md\n├── README.md                ← this file\n├── QUICKSTART.md            ← one-page install + first-skill walkthrough\n├── CHANGELOG.md             ← per-version history with breaking-change markers\n├── install.sh / install.ps1 ← interactive one-command installers\n├── docs/                    ← full documentation (start at docs/README.md)\n├── .github/                 ← copilot-instructions.md + self-CI workflow\n├── .claude-plugin/          ← Claude Code plugin + marketplace manifests\n├── .codex-plugin/           ← Codex CLI manifest\n├── gemini-extension.json    ← Gemini CLI extension manifest\n├── commands/                ← slash commands (/integration-init)\n├── references/              ← cross-skill references (tool mappings, checkpointing, CI templates)\n├── skills/                  ← the six meta-skills + INDEX.jsonl (host-neutral)\n├── agents/                  ← specialized sub-agents (code-reviewer)\n└── scripts/                 ← stdlib-only helpers (sgt.py, agent_audit.py, install.sh, …)\n```\n\n---\n\n## Documentation\n\nStart at the hub: [`docs/README.md`](docs/README.md). Key entry points:\n\n- [`QUICKSTART.md`](QUICKSTART.md) — install, verify, author, gate — on one page\n- [`docs/installation.md`](docs/installation.md) — install / upgrade / distribution (GitHub + GitLab)\n- [`docs/user-guide.md`](docs/user-guide.md) — workflows, examples, skill map\n- [`docs/agent-governance-engine.md`](docs/agent-governance-engine.md) — CLI / MCP / Docker audit engine\n- [`docs/skill-authoring-standard.md`](docs/skill-authoring-standard.md) — canonical SKILL.md skeleton\n- [`docs/checks-reference.md`](docs/checks-reference.md) — every governance check + rationale\n- [`docs/extending-checks.md`](docs/extending-checks.md) — add / remove / tune a check; propose an org rule\n\n---\n\n## License\n\nMIT (see `LICENSE`).\n",
  "bytes": 13395,
  "sha": "c7594fb3ff0ff5990f8a75ba5b8c89276c22592cb686e5f98dfbe6afa6f545d8",
  "repo_slug": "artemrudenko/skill-governance-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_artemrudenko_skill_governance_toolkit_42d31777/readme"
}