Skip to content

Commit 20de2eb

Browse files
geledekclaude
andcommitted
scripts: add bump_version.py, CLAUDE.md, skill template, golden prompts
- scripts/bump_version.py: single-command version bump across plugin.json, marketplace.json, and CHANGELOG.md (validator already enforces agreement) - CLAUDE.md: repo conventions for Claude Code sessions - templates/SKILL.md.tmpl: new-skill starting point with pre-PR checklist, now referenced from CONTRIBUTING.md - tests/golden-prompts.md: one trigger prompt per skill + output contract for regression-checking skill edits - manifest polish: repository + keywords in plugin.json, owner email in marketplace.json Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 2940d9a commit 20de2eb

8 files changed

Lines changed: 265 additions & 2 deletions

File tree

.claude-plugin/marketplace.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "enterprise-ai-transformation-skills",
33
"owner": {
44
"name": "Ray Han",
5-
"email": ""
5+
"email": "ray@rayhan.ai"
66
},
77
"metadata": {
88
"description": "Fifteen installable skills for diagnosing, designing, governing, and scaling enterprise AI transformation — distilled from 21 flagship research sources (Stanford, MIT, McKinsey, BCG, Deloitte, PwC, Accenture, NIST, EU AI Act, IMDA, WEF).",

.claude-plugin/plugin.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,18 @@
66
"author": "Ray Han",
77
"license": "MIT",
88
"homepage": "https://github.com/geledek/enterprise-ai-transformation-skills",
9+
"repository": "https://github.com/geledek/enterprise-ai-transformation-skills",
10+
"keywords": [
11+
"enterprise-ai",
12+
"ai-transformation",
13+
"ai-governance",
14+
"ai-strategy",
15+
"roi",
16+
"pilot-design",
17+
"eu-ai-act",
18+
"nist-ai-rmf",
19+
"decision-frameworks"
20+
],
921
"skills": [
1022
"skills/general-idea-diagnostic",
1123
"skills/general-use-case-discovery",

CHANGELOG.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ All notable changes to this plugin are documented here.
66

77
### Added
88
- `scripts/validate.py` + GitHub Action (`.github/workflows/validate.yml`) — CI consistency check on every push/PR: every reference pointer in a SKILL.md resolves, `_index.md` consumer columns match actual citations, plugin manifests match the `skills/` directories, versions agree across manifests, and skill frontmatter is well-formed.
9+
- `CLAUDE.md` — repo conventions for Claude Code sessions (bucket prefixes, reference-pointer rule, verdict-vocabulary stability, validator, release flow).
10+
- `templates/SKILL.md.tmpl` — starting point for new skills, with frontmatter shape, role structure, and a pre-PR checklist.
11+
- `scripts/bump_version.py` — single-command version bump across `plugin.json`, `marketplace.json`, and the changelog.
12+
- `tests/golden-prompts.md` — one trigger prompt per skill plus its output contract, for regression-checking skill edits.
13+
- Each SKILL.md References section now states where reference files live (`${CLAUDE_PLUGIN_ROOT}/references/`), making retrieval deterministic when installed as a plugin.
14+
- Plugin manifest metadata: `repository` + `keywords` in `plugin.json`, owner email in `marketplace.json`.
915

1016
### Fixed
1117
- **Broken reference pointer.** Three skills (`tech-buy-vs-build`, `tech-stack-diagnostic`, `general-peer-cases`) and `references/_index.md` cited `nanda-tech-buy-vs-build.md`, but the file on disk was named `nanda-buy-vs-build.md`. The file has been renamed to match the citations.

CLAUDE.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# CLAUDE.md
2+
3+
This repo is a Claude Code plugin: 15 prompt-only skills for enterprise AI
4+
transformation. No build step, no runtime dependencies — everything is
5+
markdown plus two JSON manifests.
6+
7+
## Layout
8+
9+
- `skills/<bucket>-<name>/` — one directory per skill: `SKILL.md` (the skill),
10+
`README.md` (human-facing summary), optional `cases/` (worked examples).
11+
Buckets: `general-` (strategy/diagnosis), `process-` (pilot/ship/observe),
12+
`tech-` (stack/sourcing/data/agents), `people-` (leadership/workforce/frontline).
13+
- `references/` — 200–500-word research extracts skills cite by bare filename.
14+
`references/_index.md` is the catalog; its consumer columns are validated
15+
against actual citations.
16+
- `.claude-plugin/plugin.json` + `marketplace.json` — both list all 15 skills
17+
and carry the version; they must stay in sync (CI checks this).
18+
- `templates/SKILL.md.tmpl` — starting point for new skills.
19+
- `docs/` — usage guide, demo scripts, effectiveness reports.
20+
21+
## Conventions
22+
23+
- Skills cite reference files by bare filename in backticks, e.g.
24+
``consult `95-5-genai-divide.md` `` — resolved against `references/` at the
25+
plugin root. Every citation must resolve to a real file.
26+
- Adding/renaming a skill requires updating BOTH `.claude-plugin/plugin.json`
27+
and `.claude-plugin/marketplace.json`, plus `README.md` tables and
28+
`INSTALL.md` trigger-phrase tables.
29+
- Each skill's verdict vocabulary (e.g. Fund / Reframe / Kill) is a stable
30+
output contract — do not rename verdicts; downstream users depend on them.
31+
- Skill H1 titles read `<Bucket> — <Title>` (e.g. `# General — AI Idea Diagnostic`).
32+
- Frontmatter: `name` must match the directory name; `description` ≤ 1024 chars
33+
and must include the trigger phrases.
34+
- Commit style: `<skill-or-ref>: <what changed>`
35+
(e.g. `general-roi-gate: tighten Q3 measurement prompt`).
36+
- Notable changes go under `## [Unreleased]` in `CHANGELOG.md`.
37+
38+
## Before committing
39+
40+
Run the consistency validator — CI runs the same script on every push/PR:
41+
42+
```bash
43+
python3 scripts/validate.py
44+
```
45+
46+
## Releasing
47+
48+
```bash
49+
python3 scripts/bump_version.py 0.4.0
50+
```
51+
52+
Updates both manifests and stamps the `[Unreleased]` changelog section with
53+
the version and date.

CONTRIBUTING.md

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Drop a diagnosed case file into `skills/general-idea-diagnostic/cases/`. Use the
1414

1515
### 3. Fork a skill
1616

17-
Copy any `SKILL.md`, rename it, and adjust:
17+
Start from `templates/SKILL.md.tmpl` (it carries the frontmatter shape, role
18+
structure, and a pre-PR checklist), or copy any `SKILL.md`, rename it, and adjust:
1819
- `name` and `description` frontmatter
1920
- Role instructions (add sector-specific context, internal process names, role titles)
2021
- Reference pointers (point to your own reference files or internal docs)
@@ -40,6 +41,20 @@ PRs not accepted for:
4041
- Breaking changes to existing skill output shapes
4142
- Vendor-specific promotions
4243

44+
## Before opening a PR
45+
46+
Run the consistency validator — CI runs the same script and will reject drift:
47+
48+
```bash
49+
python3 scripts/validate.py
50+
```
51+
52+
It checks that every reference pointer resolves, `references/_index.md`
53+
matches actual citations, the plugin manifests match the `skills/`
54+
directories, and frontmatter is well-formed. If you changed a skill's
55+
behavior, re-run its row from `tests/golden-prompts.md` and confirm the
56+
verdict vocabulary is unchanged.
57+
4358
## Commit style
4459

4560
`<skill-or-ref>: <what changed>`

scripts/bump_version.py

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/usr/bin/env python3
2+
"""Bump the plugin version in every place it lives.
3+
4+
Usage: python3 scripts/bump_version.py 0.4.0
5+
6+
Updates .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and
7+
stamps the CHANGELOG.md `## [Unreleased]` heading with the version and
8+
today's date. Refuses to run if there is no [Unreleased] section or the
9+
version is not newer than the current one.
10+
"""
11+
12+
import datetime
13+
import json
14+
import os
15+
import re
16+
import sys
17+
18+
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
19+
20+
21+
def fail(msg: str) -> None:
22+
print(f"error: {msg}", file=sys.stderr)
23+
sys.exit(1)
24+
25+
26+
def main() -> None:
27+
if len(sys.argv) != 2 or not re.fullmatch(r"\d+\.\d+\.\d+", sys.argv[1]):
28+
fail(f"usage: {sys.argv[0]} <major.minor.patch>")
29+
new = sys.argv[1]
30+
31+
plugin_path = os.path.join(ROOT, ".claude-plugin", "plugin.json")
32+
market_path = os.path.join(ROOT, ".claude-plugin", "marketplace.json")
33+
changelog_path = os.path.join(ROOT, "CHANGELOG.md")
34+
35+
plugin = json.load(open(plugin_path))
36+
current = plugin["version"]
37+
if tuple(map(int, new.split("."))) <= tuple(map(int, current.split("."))):
38+
fail(f"new version {new} is not newer than current {current}")
39+
40+
changelog = open(changelog_path).read()
41+
if "## [Unreleased]" not in changelog:
42+
fail("CHANGELOG.md has no ## [Unreleased] section to release")
43+
44+
# plugin.json — rewrite via json to keep it canonical
45+
plugin["version"] = new
46+
with open(plugin_path, "w") as f:
47+
json.dump(plugin, f, indent=2, ensure_ascii=False)
48+
f.write("\n")
49+
50+
market = json.load(open(market_path))
51+
market["metadata"]["version"] = new
52+
with open(market_path, "w") as f:
53+
json.dump(market, f, indent=2, ensure_ascii=False)
54+
f.write("\n")
55+
56+
today = datetime.date.today().isoformat()
57+
changelog = changelog.replace("## [Unreleased]", f"## [{new}] — {today}", 1)
58+
open(changelog_path, "w").write(changelog)
59+
60+
print(f"bumped {current} -> {new} in plugin.json, marketplace.json, CHANGELOG.md")
61+
print("review the diff, then commit with e.g.:")
62+
print(f' git commit -am "release: {new}"')
63+
64+
65+
if __name__ == "__main__":
66+
main()

templates/SKILL.md.tmpl

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
name: <bucket>-<skill-slug>
3+
description: Use when <the situation this skill addresses>. Phrases like "<trigger phrase 1>", "<trigger phrase 2>", "<trigger phrase 3>" all trigger this skill. <One sentence on the method — e.g. "Runs a four-role gap analysis (X / Y / Z / W)">. Outputs <the verdict vocabulary or artifact — e.g. "Fund / Reframe / Kill" or "a 90-day pilot plan with Day 30/60/90 gates">.
4+
---
5+
6+
# <Bucket> — <Human-Readable Title>
7+
8+
<One-paragraph statement of what this skill does and when it runs. Name the
9+
methodology: N sequential roles / steps. State that prior reasoning is
10+
maintained as context — each role builds on the previous. Instruct the model
11+
to complete all roles without stopping.>
12+
13+
---
14+
15+
## Role 1: <Role Name> (<the question this role answers>)
16+
17+
<Instructions for this role. Be imperative and specific. Where a claim rests
18+
on research, cite the reference file by bare filename:>
19+
*Consult `<reference-file>.md` — <one-line reminder of what it contains>.*
20+
21+
Output:
22+
<PIPE | SEPARATED | SECTION | LABELS>
23+
24+
---
25+
26+
## Role 2: <Role Name> (<question>)
27+
28+
<...repeat per role. Keep 4–7 roles. The final role is always a synthesis
29+
that reads the prior outputs and produces the verdict — it must not introduce
30+
new assessment.>
31+
32+
---
33+
34+
## Role N: <Synthesis Role Name>
35+
36+
Read the outputs of Roles 1 to N-1. Produce the verdict. Do not introduce new
37+
assessment here. Write for a board audience. Be direct.
38+
39+
VERDICT: [<Verdict-1> / <Verdict-2> / <Verdict-3>]
40+
41+
<2-sentence summaries per prior role's question>
42+
43+
STRONGEST LINK: <where the subject is most solid>
44+
WEAKEST LINK: <where it is most at risk of failing silently>
45+
ONE CHANGE: <specific action — not a general recommendation>
46+
47+
---
48+
49+
## References
50+
51+
*All files below live in `references/` at the plugin root (`${CLAUDE_PLUGIN_ROOT}/references/` when installed as a plugin).*
52+
53+
- `<reference-file>.md` — <one line on what it contributes to this skill>
54+
55+
<!--
56+
Checklist before opening a PR (CI enforces most of this via scripts/validate.py):
57+
[ ] Directory name matches frontmatter `name` and carries a bucket prefix
58+
[ ] description ≤ 1024 chars and contains the trigger phrases
59+
[ ] Every cited reference file exists in references/ and has an _index.md row
60+
[ ] Skill added to BOTH .claude-plugin/plugin.json and marketplace.json
61+
[ ] README.md added next to this file; README + INSTALL.md tables updated
62+
[ ] Verdict vocabulary does not collide with another gating skill's
63+
(see "Cross-skill cautions" in the root README)
64+
[ ] Trigger prompt + expected output shape added to tests/golden-prompts.md
65+
-->

tests/golden-prompts.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Golden prompts
2+
3+
One trigger prompt per skill plus the output contract it must honor. Use this
4+
to regression-check skill edits: run the prompt against the edited skill and
5+
confirm (a) the skill triggers, (b) all roles/steps execute in order, and
6+
(c) the final verdict uses exactly the vocabulary listed here. The verdict
7+
vocabularies are stable output contracts — see CLAUDE.md.
8+
9+
The effectiveness reports in `docs/effectiveness/` are point-in-time runs of
10+
prompts like these; re-running this table after a skill change makes results
11+
comparable across versions.
12+
13+
## General
14+
15+
| Skill | Golden prompt | Expected output contract |
16+
|---|---|---|
17+
| `general-idea-diagnostic` | "Should we pursue an AI agent that auto-approves expense reports under S$200?" | 5 roles (Investigator, Devil's Advocate, Long-term Strategist, Realist, Senior Advisor); verdict **Fund / Fund-with-condition / Reframe / Kill** + mode **Replace / Augment / Create**; names closest case from `cases/` |
18+
| `general-use-case-discovery` | "Where should we point AI first across our claims operation?" | Ranked candidate list; per-candidate verdict **Greenlight / Stage-and-watch / Park / Reject**; customer-facing candidates default to Stage-and-watch without sponsor-signed risk acceptance |
19+
| `general-maturity-assessment` | "Where are we on the AI maturity curve, and what's next?" | MIT CISR stage placement (Stage 1–4) + Accenture archetype; named next-stage actions |
20+
| `general-peer-cases` | "Has anyone else deployed AI for member services at a financial cooperative?" | Asker profile, case bundle, cross-case patterns; confidence state incl. **No-analog-found** when <3 archetype matches (must not fabricate cases) |
21+
| `general-roi-gate` | "Run the ROI gate on this AI investment proposal" | PwC 20-item checklist + three-channel ROI; recommendation **Approve / Approve-with-conditions / Return-for-revision / Reject** |
22+
23+
## Process
24+
25+
| Skill | Golden prompt | Expected output contract |
26+
|---|---|---|
27+
| `process-pilot-design` | "Design a 90-day pilot for an RM call-prep summarizer at our private bank." | 90-day plan with Day 30 / Day 60 / Day 90 gates, pre-deployment metrics, stop conditions, pass/fail verdict criterion |
28+
| `process-productionization` | "Demo works — how do we move it to production?" | 5-stage playbook + 15-item gate; verdict **GO / CONDITIONAL GO / NO-GO** with remediation list and rollout schedule |
29+
| `process-portfolio-observability` | "We deployed 11 agents but can't see what they're earning. Help." | Three-layer KPI tree + dashboard spec, net-of-oversight ROI; verdict **Observable-and-governed / Partial-observability / Black-box** |
30+
31+
## Tech
32+
33+
| Skill | Golden prompt | Expected output contract |
34+
|---|---|---|
35+
| `tech-stack-diagnostic` | "Diagnose our AI tech stack — where's the weakest link?" | Six-layer stack assessment naming the single weakest layer + remediation priority |
36+
| `tech-buy-vs-build` | "Should we build, buy, or partner for this AI capability?" | Per-component **Buy / Build** verdicts + investment verdict; applies "buy the model, build the orchestration" |
37+
| `tech-data-deployment` | "Where can this data legally run? ChatGPT? Enterprise SaaS? VPC?" | Deployment-tier mapping per data class; verdict **Approved / Conditional / Blocked** |
38+
| `tech-agent-guardrail` | "We're about to launch an AI agent — is it safely governed?" | IMDA four-dimension + NIST RMF assessment; verdict **Deploy / Deploy-with-conditions / Do-not-deploy-until-gaps-addressed** |
39+
40+
## People
41+
42+
| Skill | Golden prompt | Expected output contract |
43+
|---|---|---|
44+
| `people-readiness-conversation` | "Why isn't our AI investment moving the needle? Surface the people gaps." | 4-role gap report (CEO / Manager / Employee / HR); per-layer rating **STRONG / DEVELOPING / CRITICAL-GAP** with actions per gap |
45+
| `people-literacy-curriculum` | "We need an AI literacy program that satisfies EU AI Act Article 4." | Role-based curriculum + Art. 4 evidence plan; verdict **Compliant-and-effective / Compliant-not-effective / Non-compliant** |
46+
| `people-frontline-engagement` | "Our senior lawyers are openly hostile to the contract-review AI. What now?" | Co-design engagement plan incl. pilot-window no-headcount-cut clause; verdict **Co-designed / Imposed-with-resistance / Stalled** |

0 commit comments

Comments
 (0)