{"id":47796159,"url":"https://github.com/bcbeidel/claude-skill-governance-template","last_synced_at":"2026-04-03T16:24:17.848Z","repository":{"id":346925944,"uuid":"1192137723","full_name":"bcbeidel/claude-skill-governance-template","owner":"bcbeidel","description":"[Experimental] Template repo for managing Claude skills with automated risk auditing, approval gates, and multi-surface deployment. Fork it, add skills, get governance.","archived":false,"fork":false,"pushed_at":"2026-03-26T04:56:37.000Z","size":98,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"production","last_synced_at":"2026-03-26T23:35:04.314Z","etag":null,"topics":["ai-security","claude","claude-code","experimental","governance","owasp","plugin","risk-assessment","skills"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcbeidel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"docs/governance/_index.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-25T23:36:14.000Z","updated_at":"2026-03-26T04:56:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bcbeidel/claude-skill-governance-template","commit_stats":null,"previous_names":["bcbeidel/claude-automode-experiment"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bcbeidel/claude-skill-governance-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcbeidel%2Fclaude-skill-governance-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcbeidel%2Fclaude-skill-governance-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcbeidel%2Fclaude-skill-governance-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcbeidel%2Fclaude-skill-governance-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcbeidel","download_url":"https://codeload.github.com/bcbeidel/claude-skill-governance-template/tar.gz/refs/heads/production","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcbeidel%2Fclaude-skill-governance-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31362723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-security","claude","claude-code","experimental","governance","owasp","plugin","risk-assessment","skills"],"created_at":"2026-04-03T16:24:13.667Z","updated_at":"2026-04-03T16:24:17.840Z","avatar_url":"https://github.com/bcbeidel.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Skill Governance Template\n\n\u003e **Experimental** — This is an early-stage template exploring skill\n\u003e governance patterns. Expect rough edges. Feedback welcome.\n\nA template repository for managing, reviewing, and deploying Claude Code\nskills with built-in governance. Fork this repo to get automated risk\nauditing, approval gates, and deployment pipelines for your organization's\nClaude skills.\n\n```\n                          skills/\n                       (source of truth)\n                             |\n               +-------------+-------------+\n               |                           |\n          feature branch              make package\n               |                           |\n         Pull Request                  dist/*.zip\n               |                           |\n     +---------+---------+                 |\n     |                   |                 |\n Audit Workflow    Approval Gate      claude.ai\n     |                   |          (manual upload)\n Risk Report        LOW  = 1 review\n (PR comment)       MED  = 2 reviews\n     |              HIGH = 3 reviews\n     |                   |\n     +--------+----------+\n              |\n     Merge to production\n              |\n    +---------+---------+\n    |                   |\nDeploy Pipeline    git tag v1.x\n    |                   |\nClaude API       GitHub Release\n(automatic)      (ZIP artifacts)\n    |\nClaude Code\n(plugin install)\n```\n\n## Table of Contents\n\n- [Quickstart](#quickstart)\n- [Repository Structure](#repository-structure)\n- [Governance Policy](#governance-policy)\n- [Adding a New Skill](#adding-a-new-skill)\n- [Reviewing an Audit Report](#reviewing-an-audit-report)\n- [Deploying to Production](#deploying-to-production)\n- [Distribution](#distribution)\n- [Releasing](#releasing)\n- [Audit-Skill Details](#audit-skill-details)\n\n---\n\n## Quickstart\n\nGet working governance in your organization in 4 steps.\n\n### Step 1: Fork the Repository\n\nFork this repo into your GitHub organization. Clone it locally.\n\n### Step 2: Configure GitHub Secrets\n\nAdd your Anthropic API key as a repository secret:\n\n1. Go to **Settings \u003e Secrets and variables \u003e Actions**\n2. Click **New repository secret**\n3. Name: `ANTHROPIC_API_KEY`\n4. Value: Your Anthropic API key (workspace-scoped)\n\nThis key is used by the audit workflow (to invoke Claude for skill\nevaluation) and the deployment workflow (to upload skills via the\nSkills API).\n\n### Step 3: Create Branches\n\nCreate the `development` and `production` branches:\n\n```bash\ngit checkout -b development\ngit push -u origin development\n\ngit checkout -b production\ngit push -u origin production\n```\n\n### Step 4: Configure Branch Protection\n\nIn **Settings \u003e Branches**, add protection rules for both `development`\nand `production`:\n\n**For `development`:**\n- Require a pull request before merging\n- Require status checks to pass before merging\n  - Add required check: `skill-audit/approval-gate`\n- Do not allow bypassing the above settings\n\n**For `production`:**\n- Require a pull request before merging\n- Require status checks to pass before merging\n  - Add required check: `skill-audit/approval-gate`\n- Require approvals (minimum 1)\n- Do not allow bypassing the above settings\n\nThe `skill-audit/approval-gate` status check is set by the audit\nworkflow. It will appear as a required check after the first PR that\nmodifies a skill triggers the workflow.\n\n**Done.** Your organization now has automated skill governance.\n\n---\n\n## Repository Structure\n\n```\n.claude-plugin/\n  plugin.json                 # Plugin manifest (name, version, description)\nskills/\n  audit-skill/                # Built-in risk audit skill\n    SKILL.md                  # Skill definition (evaluation workflow)\n    references/\n      scoring-rubric.md       # 7-dimension scoring criteria\n      report-template.md      # Audit report output format\n.github/\n  workflows/\n    skill-audit.yml           # PR-triggered audit workflow\n    deploy-skills.yml         # Production deployment workflow\n    release.yml               # Tag-triggered release with ZIP artifacts\n  scripts/\n    detect-skill-changes.sh   # Detects changed skills in a PR\n    post-audit-comment.sh     # Posts/updates audit report PR comments\n    check-approvals.sh        # Enforces risk-based approval gates\n    deploy-skills.sh          # Deploys skills via Anthropic Skills API\nevals/\n  test-skills/                # Test fixtures for audit validation\n    low-risk-skill/           # Expected: LOW rating\n    medium-risk-skill/        # Expected: MEDIUM rating\n    high-risk-skill/          # Expected: HIGH rating\ndocs/\n  research/                   # Research findings with citations\n  context/                    # Distilled context from research\n  designs/                    # Design specifications\n  plans/                      # Implementation plans\nMakefile                      # make package — generates ZIPs for claude.ai\nCHANGELOG.md                  # Change history with PR links\n```\n\n---\n\n## Governance Policy\n\n### Branch Model\n\n| Branch | Purpose | Protection |\n|--------|---------|------------|\n| `development` | Integration branch for skill development | PR-only, audit status check required |\n| `production` | Deployed skills — merges here trigger deployment | PR-only, audit status check required |\n| `feature/*` | Individual skill work | No protection (short-lived) |\n\nAll changes flow through pull requests. Direct pushes to `development`\nand `production` are blocked by branch protection.\n\n### Risk-Based Approval Requirements\n\nWhen a PR modifies files in `skills/`, the audit workflow automatically:\n\n1. Runs the audit-skill against each changed skill\n2. Posts a risk report as a PR comment\n3. Labels the PR with the risk level\n4. Sets a commit status check based on approval count\n\n| Risk Rating | Required Approvals | Label |\n|-------------|-------------------|-------|\n| LOW | 1 | `risk:LOW` |\n| MEDIUM | 2 | `risk:MEDIUM` |\n| HIGH | 3 | `risk:HIGH` |\n\nThe `skill-audit/approval-gate` status check blocks merge until the\nrequired number of approvals is met. When multiple skills change in one\nPR, the highest risk rating determines the approval requirement.\n\n### Audit Trail\n\nEvery deployed skill has a traceable lineage:\n\n```\nFeature Branch → PR → Audit Report (PR comment) → Approvals → Merge → Deployment\n```\n\n- **PR**: Contains the skill changes with full diff\n- **Audit Report**: Posted as a PR comment with 7-dimension scorecard\n- **Approvals**: Recorded as GitHub reviews, counted by the approval gate\n- **Deployment**: Triggered automatically on merge to `production`\n- **CHANGELOG.md**: Links each change to its PR\n\n### Risk Dimensions\n\nThe audit-skill evaluates skills across 7 dimensions, grounded in\nestablished security frameworks:\n\n| Dimension | What It Measures | Framework |\n|-----------|-----------------|-----------|\n| Permission Scope | Tools and resources the skill accesses | OWASP LLM06, Anthropic Enterprise |\n| Data Exposure | Sensitive data access and transmission | OWASP LLM02, Anthropic Enterprise |\n| Prompt Injection Surface | Vulnerability to injection attacks | OWASP LLM01, Meta's Rule of Two |\n| Blast Radius | Worst-case impact of misbehavior | OWASP ASI08, CSA CBRA |\n| Reversibility | Whether actions can be undone | CSA CBRA |\n| Semantic Overlap | Duplication with existing skills | Anthropic Enterprise |\n| Dependency Risk | External dependencies and supply chain | OWASP ASI04, SLSA, OpenSSF |\n\nEach dimension is scored 1-5 with observable, binary criteria. The overall\nrating uses a hybrid approach: average baseline with automatic escalation\ntriggers for high-risk patterns.\n\n---\n\n## Adding a New Skill\n\n### Step 1: Create a Feature Branch\n\n```bash\ngit checkout development\ngit pull origin development\ngit checkout -b feature/my-new-skill\n```\n\n### Step 2: Create the Skill Directory\n\n```bash\nmkdir -p skills/my-new-skill\n```\n\n### Step 3: Write SKILL.md\n\nCreate `skills/my-new-skill/SKILL.md` with YAML frontmatter:\n\n```yaml\n---\nname: my-new-skill\ndescription: Brief description of what this skill does and when to use it.\n---\n\n# My New Skill\n\n## Instructions\n[Step-by-step guidance for Claude to follow]\n```\n\nRequirements:\n- `name`: max 64 characters, lowercase letters/numbers/hyphens only\n- `description`: max 1024 characters, non-empty, third person\n- Body: under 500 lines for optimal performance\n\n### Step 4: Add Supporting Files (Optional)\n\n```\nskills/my-new-skill/\n  SKILL.md              # Required\n  references/           # Optional: additional docs\n  scripts/              # Optional: utility scripts\n```\n\n### Step 5: Commit and Open a PR\n\n```bash\ngit add skills/my-new-skill/\ngit commit -m \"Add my-new-skill\"\ngit push -u origin feature/my-new-skill\n```\n\nOpen a PR targeting `development`. The audit workflow will automatically\nrun and post a risk report.\n\n### Step 6: Address the Audit Report\n\nReview the audit report posted as a PR comment. If the risk rating is\nhigher than expected, follow the recommendations to reduce risk. Push\nfixes and the audit will re-run.\n\n### Step 7: Get Approvals and Merge\n\nGet the required number of approvals for the risk level. The\n`skill-audit/approval-gate` status check will turn green when met.\nMerge the PR.\n\n---\n\n## Reviewing an Audit Report\n\nWhen the audit workflow runs, it posts a comment on the PR containing\na risk report for each changed skill.\n\n### What to Look For\n\n1. **Overall Risk Rating**: LOW, MEDIUM, or HIGH at the top of the report\n2. **Scorecard**: A table showing each dimension's score (1-5) with\n   justifications citing specific evidence from the skill files\n3. **Escalation Triggers**: Any conditions that automatically elevated\n   the risk rating (e.g., unrestricted Bash access, credential handling)\n4. **Recommendations**: Actionable suggestions for dimensions scoring 3+\n\n### Red Flags\n\n- **Permission Scope 4-5**: The skill uses Bash — verify commands are\n  constrained and necessary\n- **Data Exposure 5**: The skill handles credentials or transmits data\n  externally — verify this is intended\n- **Prompt Injection 5**: The skill satisfies Meta's Rule of Two (processes\n  untrusted input + accesses sensitive data + changes state) — ensure\n  safeguards are in place\n- **Dependency Risk 4-5**: MCP tool references or unpinned dependencies —\n  verify these are trusted and necessary\n\n### Approving\n\nAfter reviewing the audit report:\n- If the scores are justified and risks are acceptable, approve the PR\n- If scores seem too high, work with the skill author on remediation\n- If you disagree with a score, document why in your review comment\n\n---\n\n## Deploying to Production\n\n### Step 1: Merge to Development\n\nAll skill changes must first be merged to `development` via PR with\na passing audit and sufficient approvals.\n\n### Step 2: Create a Production PR\n\n```bash\ngit checkout production\ngit pull origin production\ngit checkout development\ngit pull origin development\ngh pr create --base production --head development \\\n  --title \"Deploy: [description of changes]\"\n```\n\n### Step 3: Review and Merge\n\nThe audit workflow runs again on the production PR. Get required\napprovals. Merge the PR.\n\n### Step 4: Automatic Deployment\n\nOn merge to `production`, the `deploy-skills.yml` workflow automatically:\n1. Discovers all skills in `skills/`\n2. Uploads each to your Claude workspace via the Skills API\n3. Creates new skills or updates existing ones\n4. Reports deployment results in the workflow log\n\n### Verifying Deployment\n\nCheck the workflow run in **Actions \u003e Deploy Skills** to see which skills\nwere created, updated, or failed.\n\n---\n\n## Distribution\n\nSkills in this repo deploy to three surfaces. Each uses the same `skills/`\ndirectory as the source of truth.\n\n### Claude Code (Plugin Install)\n\nThis repo is structured as a Claude Code plugin. Team members install it\nfrom your plugin marketplace:\n\n```\n/plugin install \u003cyour-marketplace-url\u003e\n```\n\nSkills auto-discover on install. Updates via `/plugin update`.\n\n### Claude API (Automatic)\n\nOn merge to `production`, the `deploy-skills.yml` workflow automatically\nuploads all skills to your Claude API workspace via the Skills API. These\nskills are available in Messages API calls with `container.skills`.\n\nThe deploy script detects orphaned skills (deployed but removed from repo)\nand warns in the summary. To remove orphans:\n\n```bash\nANTHROPIC_API_KEY=\u003ckey\u003e .github/scripts/deploy-skills.sh --delete-orphans\n```\n\n### claude.ai (Manual ZIP Upload)\n\nclaude.ai requires manual upload through the admin UI. Generate ZIP files:\n\n```bash\nmake package\n# → dist/audit-skill.zip\n# → dist/your-skill.zip (one ZIP per skill in skills/)\n```\n\nThen upload each ZIP:\n1. Go to **Organization Settings \u003e Skills \u003e + Add**\n2. Select the ZIP file\n3. Set default state (enabled/disabled)\n\nZIP files are also attached to GitHub Releases for download.\n\n\u003e **Note:** Custom Skills on claude.ai do not sync with the API or Claude\n\u003e Code. Each surface must be updated independently. This is an Anthropic\n\u003e platform limitation.\n\n---\n\n## Releasing\n\n### Create a Release\n\n1. Update the version in `.claude-plugin/plugin.json`\n2. Commit and merge to `production`\n3. Tag and push:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\n4. The `release.yml` workflow creates a GitHub Release with:\n   - Skill ZIP files attached as downloadable assets\n   - Auto-generated release notes\n   - Instructions for each deployment surface\n\n### Version Strategy\n\n- Use [semantic versioning](https://semver.org/) in `.claude-plugin/plugin.json`\n- Bump **patch** for skill content changes (rubric updates, report tweaks)\n- Bump **minor** for new skills added\n- Bump **major** for breaking changes (scoring methodology changes, API changes)\n\n---\n\n## Audit-Skill Details\n\nThe audit-skill at `skills/audit-skill/` is itself a Claude Code skill\nthat evaluates other skills. It:\n\n- Reads a target skill directory (SKILL.md, scripts, references)\n- Extracts observable facts (tools, commands, data patterns, URLs)\n- Scores 7 risk dimensions using a deterministic rubric\n- Generates a report with scorecard, justifications, and recommendations\n\nThe scoring rubric is at `skills/audit-skill/references/scoring-rubric.md`.\nThe report template is at `skills/audit-skill/references/report-template.md`.\n\nThe audit-skill passes its own audit with a LOW rating (average 1.7/5.0).\n\n### Scoring Methodology\n\n- Each dimension scored 1-5 with observable, binary criteria\n- Overall rating: average of all 7 scores\n- Escalation triggers override the average:\n  - Any single score of 5 → at least MEDIUM\n  - Any two scores of 4+ → HIGH\n  - Anthropic high-concern patterns → at least MEDIUM\n\nSee `skills/audit-skill/references/scoring-rubric.md` for the complete\ncriteria and calibration examples.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcbeidel%2Fclaude-skill-governance-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcbeidel%2Fclaude-skill-governance-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcbeidel%2Fclaude-skill-governance-template/lists"}