skills: front-load output contracts; tests: add routing prompts; validate: size budget WARN

Learnings adopted from the book-to-skill ecosystem (virgiliojr94/book-to-skill,
Skill_Seekers, Hassid's 5-minute method):
- All 16 SKILL.md files state verdict vocabulary + boundary pointers before
  Role 1, so the contract survives context compaction
- tests/golden-prompts.md gains 9 negative-trigger routing prompts incl. a
  dormancy check
- scripts/validate.py warns (non-fatal) when a SKILL.md exceeds ~4K tokens
- templates/SKILL.md.tmpl + CONTRIBUTING.md codify the five distillation
  questions, negative triggers, and counterfactual-reproduction checklist

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: geledek

CHANGELOG.md

@@ -5,8 +5,14 @@ All notable changes to this plugin are documented here.
 ## [Unreleased]
 
 ### Added
+- Routing (negative-trigger) tests in `tests/golden-prompts.md` — nine prompts that must route to one skill and must NOT activate its adjacent sibling (tool-selection vs. literacy-curriculum, idea-diagnostic vs. roi-gate, data-deployment vs. agent-guardrail, …), plus a dormancy check. Inspired by the book-to-skill ecosystem's activation/dormancy testing.
+- Size-budget warning in `scripts/validate.py` — non-fatal WARN when a SKILL.md exceeds ~4K tokens (16K chars), keeping skills one-gulp loadable.
+- Distillation guide — the five extraction questions for turning a book, framework, or real decision into a skill, in `templates/SKILL.md.tmpl` and `CONTRIBUTING.md`, with negative-trigger and counterfactual-reproduction requirements in the pre-PR checklist.
 - **New skill: `people-tool-selection`** — six-role selector for choosing which AI tool to put in front of a specific user group (training cohort, team, department). Constraint-first method: hard eliminators (cost, ecosystem, setup friction, data, language, IT policy) filter candidates before capability comparison; then picks an intervention mode (Deepen / Extend / Introduce) and ranks survivors by new-artifact delta per unit of friction. Outputs Adopt-now / Adopt-with-scaffolding / Pilot-with-subgroup / Skip plus a first-win exercise and growth path. Ships with the Mongolian-teachers reference case (NotebookLM chosen over advanced prompting, agent skills, and Manus). Skill count is now 16.
 
+### Changed
+- All 16 SKILL.md files now front-load their output contract — verdict vocabulary (and boundary pointers to adjacent skills) stated before Role 1, so the contract survives context compaction.
+
 ## [0.4.0] — 2026-07-02
 
 ### Added

CONTRIBUTING.md

@@ -22,6 +22,25 @@ structure, and a pre-PR checklist), or copy any `SKILL.md`, rename it, and adjus
 
 Example forks: sector-specific (`general-idea-diagnostic-healthtech`), internal process-aware (`roi-gate-[company]`), role-specific (`people-readiness-conversation-board`).
 
+### 4. Distill a new skill from a book or your own practice
+
+The skills here are distilled decision processes. To add one, answer five
+questions before writing any role (the full version lives in
+`templates/SKILL.md.tmpl`):
+
+1. What decision does the skill gate, and who stands behind the verdict?
+2. What are the sequential questions? Each "because" in the original reasoning becomes a role.
+3. Which criteria are hard filters (eliminate) vs. ranking criteria (compare)? Keep them in separate roles.
+4. Which failure modes deserve their own role?
+5. What verdict vocabulary fits — without colliding with another skill's?
+
+Then define 2–3 **negative triggers** — adjacent prompts that must route to a
+*different* skill — and add them to the routing table in
+`tests/golden-prompts.md`. Before merging, confirm the skill reproduces the
+case that inspired it, and that one counterfactual (a changed input) flips the
+verdict. `skills/people-tool-selection/` with its `cases/` file is the worked
+example of this process.
+
 ## What not to change in a fork
 
 - The structural role sequence — it's the methodology, not a style choice

scripts/validate.py

@@ -13,6 +13,8 @@
   5. plugin.json version == marketplace.json metadata.version.
   6. Every skill has SKILL.md + README.md; frontmatter `name` matches the
      directory name; `description` present and <= 1024 chars.
+  7. WARN (non-fatal) when a SKILL.md body exceeds ~4K tokens — skills should
+     stay loadable in one gulp; density over completeness.
 
 Exits non-zero with a list of failures if anything is inconsistent.
 """
@@ -23,13 +25,19 @@
 import sys
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SKILL_SIZE_BUDGET = 16_000  # chars, ~4K tokens
 errors = []
+warnings = []
 
 
 def err(msg: str) -> None:
     errors.append(msg)
 
 
+def warn(msg: str) -> None:
+    warnings.append(msg)
+
+
 def frontmatter(text: str) -> dict:
     m = re.match(r"\A---\n(.*?)\n---\n", text, re.DOTALL)
     fields = {}
@@ -70,6 +78,13 @@ def frontmatter(text: str) -> dict:
     elif len(desc) > 1024:
         err(f"skills/{skill}/SKILL.md: description is {len(desc)} chars (limit 1024)")
 
+    # check 7: size budget (warning only)
+    if len(body) > SKILL_SIZE_BUDGET:
+        warn(
+            f"skills/{skill}/SKILL.md is {len(body):,} chars "
+            f"(budget {SKILL_SIZE_BUDGET:,} ≈ 4K tokens) — consider moving detail to references/ or cases/"
+        )
+
     # check 1: every backticked .md pointer resolves
     for ref in set(re.findall(r"`([a-z0-9-]+\.md)`", body)):
         in_references = os.path.isfile(os.path.join(ROOT, "references", ref))
@@ -143,6 +158,8 @@ def frontmatter(text: str) -> dict:
     err(f"version drift — plugin.json has {pv!r}, marketplace.json has {mv!r}")
 
 # ---- report ---------------------------------------------------------------
+for w in warnings:
+    print(f"  WARN - {w}")
 if errors:
     print(f"FAIL — {len(errors)} issue(s):\n")
     for e in errors:

skills/general-idea-diagnostic/SKILL.md

@@ -7,6 +7,8 @@ description: Use when evaluating an AI idea, AI concept, or early-stage AI propo
 
 Diagnose an AI idea at concept stage — before pilot design, before investment, before any build decision. Five sequential roles. Maintain all prior reasoning as state — each role builds on the previous.
 
+Verdict vocabulary (stable output contract): **Fund / Fund-with-condition / Reframe / Kill**, plus solution mode **Replace / Augment / Create**. This gates the *concept*; the funding decision comes later — use `general-roi-gate` for investment approval.
+
 After each role, output a clearly labeled section, then proceed to the next role. Do not stop until all five are complete.
 
 ---

skills/general-maturity-assessment/SKILL.md

@@ -9,6 +9,8 @@ Plot the organization on the AI maturity curve. Identify the binding constraint.
 
 Two complementary frameworks: MIT CISR's four-stage sequential model (where are we, and what is next?) + Accenture's Foundation × Differentiation 2×2 (what is the binding constraint that's keeping us here?). Use both — they answer different questions.
 
+Output contract (stable): MIT CISR stage placement (**Stage 1 / Stage 2 / Stage 3 / Stage 4**) plus Accenture archetype, with named next-stage actions.
+
 ---
 
 ## Part 1: MIT CISR Stage Placement

skills/general-peer-cases/SKILL.md

@@ -11,6 +11,8 @@ Anchor base rate: 95% of GenAI pilots produce zero measurable P&L impact (MIT 20
 
 The library is bundled in `references/`. Pull cases by archetype match — not by name recall.
 
+Output contract (stable): asker profile, case bundle, cross-case patterns, and a confidence state — including **No-analog-found** when fewer than 3 archetype matches exist.
+
 ---
 
 ## Step 1: Asker Profile

skills/general-roi-gate/SKILL.md

@@ -9,6 +9,8 @@ A pre-flight risk gate before greenlighting any AI investment. Runs PwC's 20-ite
 
 This skill gates *funding decisions* — after the idea has been assessed (use `general-idea-diagnostic` for concept-stage gating) and after a pilot brief exists (use `process-pilot-design` for pilot structuring). This is the investment-approval gate.
 
+Verdict vocabulary (stable output contract): **Approve / Approve-with-conditions / Return-for-revision / Reject**.
+
 ---
 
 ## Role 1: Objective-Mode Audit

skills/general-use-case-discovery/SKILL.md

@@ -9,6 +9,8 @@ Most enterprises drown in candidate ideas and pilot the wrong one. MIT's 95/5 fi
 
 Anchor: McKinsey's three-objective mix (productivity / growth / transformation), Andrew Ng's three moats, BCG 10/20/70 effort split.
 
+Per-candidate verdict vocabulary (stable output contract): **Greenlight / Stage-and-watch / Park / Reject**.
+
 ## Role 1: Value-Pool Mapper
 
 Where is the dollar-or-hour pain, by sub-function? Do not start from "what can AI do" — start from where the bleeding is.

skills/people-frontline-engagement/SKILL.md

@@ -9,6 +9,8 @@ A five-role protocol for engaging fearful or skeptical frontline experts as co-d
 
 Stanford's 2025 enterprise study: 77% of the hardest costs in AI deployment are invisible — change management, redesign, trust. Skip this protocol and the pilot stalls inside the 95% non-impact band. Run all five roles in order. Carry every quote forward as state.
 
+Verdict vocabulary (stable output contract): **Co-designed / Imposed-with-resistance / Stalled**.
+
 ---
 
 ## Role 1: Empathic Listener

skills/people-literacy-curriculum/SKILL.md

@@ -9,6 +9,8 @@ Design a role-anchored AI literacy program that satisfies EU AI Act Art. 4 (mand
 
 Anchor: BCG 88/25 manager role-modeling — 88% of managers say role-modeling AI matters, only 25% do it visibly; weekly-AI-use rates jumped 55%→72% YoY in cohorts where managers used the tools themselves. Training without manager role-modeling is theatre.
 
+Verdict vocabulary (stable output contract): **Compliant-and-effective / Compliant-not-effective / Non-compliant**. This designs the enterprise-wide *program*; for choosing which single tool to put in front of a specific group, use `people-tool-selection`.
+
 ---
 
 ## Step 1: Mental-Model Taxonomy