@skill-graph/cli 0.5.6

package/marketplace/skills/eval-driven-development/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: eval-driven-development
+description: "Use when reasoning about building language-model-integrated systems by writing evaluations before and alongside the system: the statistical (not binary) nature of LLM evals, the five primitives (dataset, evaluation function, aggregation, iteration loop, regression budget), the judgment-mechanism taxonomy (programmatic, model-graded, human-graded, preference comparison), the difference between system-specific evals and canonical benchmarks (MMLU, HumanEval, BIG-bench, GAIA), how evals drive prompt/model/scaffolding/tooling changes, why Goodhart's Law means higher eval scores are not always improvements, and the offline-eval-vs-production-telemetry distinction. Do NOT use for deterministic unit testing (use testing-strategy), production monitoring (use evaluation or error-tracking), general-software TDD (use testing-strategy), or the construction of individual eval rubrics and task sets (use agent-eval-design — it owns construction; this skill owns the iteration discipline)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/evaluation\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"eval-driven development\\\\\\\",\\\\\\\"LLM evals\\\\\\\",\\\\\\\"evaluation harness\\\\\\\",\\\\\\\"benchmark\\\\\\\",\\\\\\\"HumanEval\\\\\\\",\\\\\\\"MMLU\\\\\\\",\\\\\\\"BIG-bench\\\\\\\",\\\\\\\"GAIA\\\\\\\",\\\\\\\"LLM-as-judge\\\\\\\",\\\\\\\"model-graded eval\\\\\\\",\\\\\\\"pass rate\\\\\\\",\\\\\\\"regression budget\\\\\\\",\\\\\\\"Goodhart's law\\\\\\\",\\\\\\\"golden dataset\\\\\\\",\\\\\\\"reference-free eval\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do we know this prompt change improved things\\\\\\\",\\\\\\\"should this be an eval or a unit test\\\\\\\",\\\\\\\"the model passes the benchmark but fails in production\\\\\\\",\\\\\\\"what should we measure\\\\\\\",\\\\\\\"the LLM-as-judge gives different scores each run\\\\\\\"]\",\"examples\":\"[\\\\\\\"design an offline eval suite for an LLM-integrated summarization feature before writing the prompt\\\\\\\",\\\\\\\"decide between programmatic grading, model-graded judgment, and human review for a freeform-output eval\\\\\\\",\\\\\\\"explain why MMLU score is a poor predictor of a domain-specific assistant's quality\\\\\\\",\\\\\\\"structure an iteration loop where each prompt change is gated by a regression budget\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"write unit tests for a deterministic data transformation (use testing-strategy)\\\\\\\",\\\\\\\"set up production alerting on API error rates (use observability)\\\\\\\",\\\\\\\"interpret a specific benchmark's leaderboard (use benchmarking-engine)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"prompt-injection-defense\\\\\\\",\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"agent-eval-design\\\\\\\",\\\\\\\"evaluation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns deterministic-software testing where every run is binary pass/fail; this skill owns LLM evaluation where every run is a sample from a distribution and pass-rate is the unit of judgment. The disciplines share vocabulary (suite, gate, regression) but the math underneath differs.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-flow owns the protocol cycle by which a model invokes tools; this skill owns the discipline of measuring whether that cycle produces correct behavior. Tool-call evals are a specialization of the general pattern.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-injection-defense\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-injection-defense owns the security property; this skill owns the measurement of whether the property holds. Red-team evals against an injection corpus are one application of eval-driven-development.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"agent-eval-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"agent-eval-design owns the construction of evals — task sets, rubrics, graders, hard negatives, traces; this skill owns the development discipline that uses constructed evals to gate every change to prompt, model, retrieval, scaffolding, or tooling. The two compose: agent-eval-design produces the suite; this skill applies it.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety owns the compile-time property of programs; this skill owns the runtime-distributional property of LLM outputs. They are both validate-at-the-boundary disciplines with different threat models.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"agent-eval-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Eval-driven development is to LLM system engineering what crash-test ratings are to automotive safety — you do not ship a car based on how well it parked in your driveway; you ship it after a battery of standardized tests on representative crash scenarios, with the pass-rate against named criteria as the gating signal. A score of 4.3 stars across the suite is the only defensible claim of 'safer'; a developer's intuition that 'the new model feels smarter' is the unmeasured equivalent of 'I drove it home, it seemed fine.'\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Eval-driven development is the practice of building language-model-integrated systems by writing evaluations before and alongside the system, where each evaluation defines a behavioral criterion the system must satisfy on a representative input set, and the suite's aggregated pass-rate signal gates every change to the prompt, model, retrieval, scaffolding, or tooling. Evals are the LLM analog of automated tests for deterministic software with one fundamental difference: LLM evals are statistical (pass-rate over a sampled population) rather than binary (pass/fail per run), because the system under test is itself stochastic. The discipline is the rigorous separation of generation (what the system produces) from judgment (how it is scored) with explicit accounting for the uncertainty in both.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/eval-driven-development/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/eval-driven-development/SKILL.md
+---
+
+# Eval-Driven Development
+
+## Coverage
+
+The practice of building language-model-integrated systems by writing evaluations before and alongside the system, and using the eval suite's aggregated pass-rate signal to gate every change. Covers the statistical (not binary) nature of LLM evaluation, the five primitives (dataset, evaluation function, aggregation, iteration loop, regression budget), the judgment-mechanism taxonomy (programmatic / model-graded / human-graded / hybrid), the distinction between system-specific evals and canonical public benchmarks (MMLU, HumanEval, BIG-bench, GAIA, MT-Bench), why higher scores are not always improvements (Goodhart's Law), the difference between offline evals and production telemetry, and the eval-lifecycle archetypes (acceptance, regression, calibration, red-team, cross-model).
+
+## Philosophy
+
+Building LLM-integrated systems without evals is shipping airplanes based on how good the model feels at the desk. The system's behavior is stochastic, the input space is open-ended, and the developer's pet examples are not a representative sample of what users will throw at it. An eval suite is the empirical measurement instrument that lets a team distinguish "the new prompt works better" from "the new prompt works better on the five examples I happened to try."
+
+The discipline's hard part is not writing evals. It is choosing what to measure, encoding the choice into a grader the team agrees with, sampling a dataset that represents production, and resisting the gravitational pull of Goodhart's Law as the eval suite becomes the optimization target. Teams that get this right ship systems whose quality matches their team's stated definition of "good." Teams that get this wrong ship systems that ace evals and disappoint users.
+
+Eval-driven development is not test-driven development with extra noise. It is empirical engineering applied to systems whose behavior is a distribution rather than a value. The vocabulary overlaps; the math underneath does not.
+
+## The Five Primitives In Practice
+
+| Primitive | What it is | Common encoding | Failure mode if neglected |
+|---|---|---|---|
+| Eval dataset | Curated input examples that represent production | JSONL of `{input, reference}` records; checked into version control | "It works for me" with no shared evidence |
+| Evaluation function | Per-example grader producing a score | Python function, model-graded prompt template, or human-review UI | Implicit, undocumented definition of "good" |
+| Aggregation | Statistical summary across the dataset | Pass-rate, weighted pass-rate, stratified pass-rate, distribution | Headline number obscures pattern of failure |
+| Iteration loop | Eval → diagnose → change → eval | CI-integrated pipeline; eval results in PR comment | Changes ship without measurement |
+| Regression budget | Defined acceptable change per metric | Per-eval policy: "must not regress" / "improvement gates merge" / "watchful" | Every change becomes a debate about the headline number |
+
+## Judgment Mechanism Selection
+
+| Mechanism | Best for | Cost per example | Reliability | Watch for |
+|---|---|---|---|---|
+| Programmatic | Outputs with mechanical correctness (code, JSON validity, exact match) | $0 | Deterministic | Narrow applicability — won't work for freeform output |
+| Model-graded | Open-output tasks at scale (summarization, classification, freeform Q&A) | $0.001-$0.10 per grade depending on model | Correlated error with the system being graded | Verbosity bias, position bias in pairwise; calibrate against humans |
+| Human-graded | Subjective criteria, calibration runs, ambiguous outputs | $1-$50 per grade depending on annotator | Highest validity; lowest scale | Inter-rater agreement must be measured; one rater is not "humans think" |
+| Hybrid | Production systems | Mixed | Mixed | Standard setup: programmatic gates, model-graded scales, human samples calibrate |
+
+A practical default: programmatic checks for the parts you can mechanically verify, model-graded for the open parts, periodic human review to calibrate.
+
+## Iteration Loop Discipline
+
+The eval-driven iteration loop is the development cycle. Run the suite, diagnose failures, identify the change, re-run, gate the change on regression budget.
+
+```
+┌─────────┐    ┌──────────┐    ┌──────────────┐    ┌──────────┐
+│ Eval    │ -> │ Diagnose │ -> │ Change       │ -> │ Re-run   │
+│ baseline│    │ failures │    │ (prompt,     │    │ Eval     │
+│         │    │          │    │  model,      │    │          │
+│         │    │          │    │  retrieval,  │    │          │
+│         │    │          │    │  tooling)    │    │          │
+└─────────┘    └──────────┘    └──────────────┘    └──────────┘
+                                                          │
+                                                          v
+                                                ┌──────────────────┐
+                                                │ Compare against  │
+                                                │ regression budget│
+                                                │ Merge / iterate  │
+                                                └──────────────────┘
+```
+
+The discipline is keeping the suite stable while the system changes. If both move in the same iteration, the comparison anchor is gone and the team is doing parallel experiments.
+
+## Public Benchmarks — Cited For Grounding, Not For Gating
+
+Benchmarks measure cross-system capability against a shared standard. They predict how a model will do on the *exact* tasks the benchmark contains. They do not predict how your specific system, on your specific user inputs, with your specific prompts and retrieval, will perform.
+
+| Benchmark | Measures | Cited for |
+|---|---|---|
+| MMLU (Hendrycks et al., 2021) | 57 subjects of multiple-choice general knowledge | Breadth of general capability |
+| HumanEval (Chen et al., 2021) | 164 programming problems graded by test execution | Code-generation correctness baseline |
+| BIG-bench (Srivastava et al., 2022) | 200+ tasks across the long tail of NLP | Breadth of niche capabilities |
+| GAIA (Mialon et al., 2023) | General-assistant multi-step tasks with tool use | Realistic agentic-task baseline |
+| MT-Bench / Chatbot Arena (Zheng et al., 2023) | Pairwise preference comparison for chat | Human-aligned preference signal |
+
+The right use: pick a model partly on benchmark performance, then build system-specific evals to gate the actual deployment.
+
+## Goodhart's Law In Eval Practice
+
+When the eval becomes the optimization target, the eval ceases to be a good measure. Symptoms:
+
+- Pass-rate climbs while human reviewers' confidence in the system flattens or declines.
+- Prompt changes produce phrasings the grader rewards but users dislike (e.g., verbose hedging that scores well on rubric, reads poorly on screen).
+- The system memorizes patterns specific to the eval dataset (over-fitting to test cases).
+- A held-out evaluation set, scored fresh, shows worse pass-rate than the development set.
+
+Defenses:
+
+- **Hold out a portion of the dataset from active iteration.** Score it periodically; if held-out and development pass-rates diverge, the iteration is over-fitting.
+- **Periodically refresh the eval dataset.** Replace some examples with new production-sampled inputs to prevent the dataset from going stale.
+- **Calibrate model-graders against humans.** A grader that has drifted from human judgment can produce high pass-rates on outputs humans dislike.
+- **Track multiple criteria.** A single headline number is easier to over-fit than a panel of independent measures.
+
+## What This Skill Is Not
+
+This skill is the *concept* of eval-driven development. Specific topics with their own scope:
+- The mechanics of running evals in CI/CD pipelines belong to a tooling skill.
+- The construction of individual eval rubrics, task sets, graders, and hard negatives belongs to `agent-eval-design`.
+- The deterministic testing of non-LLM code belongs to `testing-strategy`.
+- The production monitoring of running systems belongs to observability and reliability skills.
+- The obra/superpowers `test-driven-development` skill (on skills.sh) is a process-shape workflow skill for general software TDD; this one is the concept-shape complement for the LLM-specific evaluation discipline.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] An eval dataset exists, is checked into version control, and is representative of the system's actual production input distribution.
+- [ ] Each eval criterion has a defined judgment mechanism (programmatic, model-graded, or human-graded), and the mechanism's known biases are accounted for.
+- [ ] Aggregation reports pass-rate with sample size and either a confidence interval or a defined minimum-detectable-change threshold.
+- [ ] Each eval has an explicit regression budget: gating (no regression allowed), optimizing (improvement gates merge), or watchful (tracked, not gated).
+- [ ] Model-graded evals have been calibrated against human review on a sample within the past quarter (or whatever cadence the team has agreed to).
+- [ ] A held-out portion of the dataset is reserved from active iteration and scored periodically to detect over-fitting.
+- [ ] The eval suite is integrated into the change workflow — prompt changes, model upgrades, retrieval changes, and tooling changes are all gated by the suite.
+- [ ] Public benchmarks (MMLU, HumanEval, etc.) are cited for model-selection grounding but are not the gating decision for system-specific quality.
+- [ ] Production telemetry exists separately from the offline eval suite; one is not used as a substitute for the other.
+- [ ] The shipping threshold is a product decision documented somewhere, not an emergent average across team opinion.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Writing deterministic unit tests for non-LLM code | `testing-strategy` | testing-strategy owns binary pass/fail testing; this skill owns distributional measurement |
+| Designing individual eval rubrics, task sets, graders, hard negatives | `agent-eval-design` | agent-eval-design owns eval construction; this skill owns the iteration discipline that uses constructed evals |
+| Setting up production monitoring, alerting, or telemetry | `evaluation` (general framing) or `error-tracking` | those own runtime measurement of deployed systems; this skill owns offline pre-deployment measurement |
+| Reasoning about the protocol cycle of tool calls | `tool-call-flow` | tool-call-flow owns the cycle; eval-driven development can measure tool-call correctness as one criterion |
+| Defending against prompt injection | `prompt-injection-defense` | prompt-injection-defense owns the security property; this skill can measure whether the defense holds |
+| General software TDD process | the obra/superpowers `test-driven-development` skill or `testing-strategy` | TDD is process-shape for general software; this skill is concept-shape for the LLM-specific evaluation discipline |
+
+## Key Sources
+
+- Hendrycks, D., Burns, C., Basart, S., Zou, A., Mazeika, M., Song, D., & Steinhardt, J. (2021). ["Measuring Massive Multitask Language Understanding"](https://arxiv.org/abs/2009.03300). The MMLU benchmark paper; foundational reference for cross-system general-knowledge evaluation.
+- Chen, M., Tworek, J., Jun, H., Yuan, Q., et al. (2021). ["Evaluating Large Language Models Trained on Code"](https://arxiv.org/abs/2107.03374). The HumanEval benchmark paper; foundational for code-generation evaluation.
+- Srivastava, A., et al. (2022). ["Beyond the Imitation Game: Quantifying and extrapolating the capabilities of language models"](https://arxiv.org/abs/2206.04615). The BIG-bench paper; canonical reference for breadth-of-capability evaluation across 200+ tasks.
+- Mialon, G., Fourrier, C., Swift, C., Wolf, T., LeCun, Y., & Scialom, T. (2023). ["GAIA: A Benchmark for General AI Assistants"](https://arxiv.org/abs/2311.12983). The GAIA benchmark paper; canonical reference for evaluating multi-step assistant tasks with tool use.
+- Zheng, L., Chiang, W.-L., et al. (2023). ["Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena"](https://arxiv.org/abs/2306.05685). The MT-Bench paper; canonical reference for LLM-as-judge methodology, including known biases.
+- OpenAI. [Evals framework on GitHub](https://github.com/openai/evals). Open-source framework for writing and running LLM evals; documents the practical mechanics of the discipline.
+- Anthropic. [Building evals — Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook/tree/main/skills/classification) and [Evaluation guide](https://docs.anthropic.com/en/docs/test-and-evaluate/develop-tests). Practitioner-oriented guidance on building eval suites.
+- UK AI Safety Institute. [Inspect: An open-source evaluation framework](https://inspect.ai-safety-institute.org.uk/). Open framework purpose-built for capability and safety evaluations of LLMs.
+- Goodhart, C. (1975). "Problems of Monetary Management: The U.K. Experience." The origin of Goodhart's Law as commonly cited; "when a measure becomes a target, it ceases to be a good measure."
+- Liang, P., et al. (2022). ["Holistic Evaluation of Language Models"](https://arxiv.org/abs/2211.09110). The HELM framework paper; argues for multi-metric eval across many dimensions as a counter to single-metric Goodharting.

package/marketplace/skills/evaluation/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: evaluation
+description: "This skill provides a structured framework for automated agentic evaluation and human feedback loops. It defines the 'Critic' persona, the 5-point quality scale, and the mandatory 'Evaluation-Revision' loop for all critical work."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/skill-system\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-29\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-29\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"evaluation\\\\\\\",\\\\\\\"quality gate\\\\\\\",\\\\\\\"feedback loop\\\\\\\",\\\\\\\"critic persona\\\\\\\",\\\\\\\"evaluation revision\\\\\\\",\\\\\\\"completion contract\\\\\\\",\\\\\\\"score 1-5\\\\\\\",\\\\\\\"skeptical critic\\\\\\\"]\",\"triggers\":\"[\\\\\\\"evaluation-skill\\\\\\\",\\\\\\\"critic-loop-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/evaluation/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/evaluation/SKILL.md
+---
+# Evaluation Skill (Critic Persona)
+
+## Domain Context
+
+**What is this skill?** This skill provides a structured framework for automated agentic evaluation and human feedback loops. It defines the 'Critic' persona, the 5-point quality scale, and the mandatory 'Evaluation-Revision' loop for all critical work.
+
+## Coverage
+
+This skill covers the Skeptical Critic evaluation framework for AI agent work: the 5-point quality scale (Broken through State-of-the-Art), the mandatory Evaluation-Revision loop for all critical work, Goal Alignment auditing against implementation plans, Pattern Compliance checking (financial nullish coalescing, composition-theory focal points, semantic naming), the evaluation process flow (Persona, Identify, Score, Critique, Iterate), and the repo-specific completion contract (code + docs + Linear + verification evidence).
+
+## Philosophy
+
+Without this skill, agents self-assess as "done" after code compiles and tests pass, missing the completion contract that includes documentation updates, Linear task reporting, verification evidence, and adherence to project-specific patterns. The Skeptical Critic persona exists because agents are systematically optimistic about their own output quality. By forcing a numeric score with explicit gap identification, this skill prevents the "ship it because it works" failure mode that produces technically functional but incomplete deliverables.
+
+# MANDATORY ACTIVATION TRIGGER (SYSTEM DIRECTIVE)
+This skill MUST be activated after EVERY meaningful implementation or cleanup step. It acts as a final 'Skeptical Critic' to ensure no regressions or half-baked solutions are shipped.
+
+### EVALUATION RUBRIC (1-5 SCALE)
+1. **Broken/Unusable**: Fails basic requirements, contains bugs or syntax errors.
+2. **Partial/Risky**: Meets some goals but lacks edge-case coverage or violates security rules.
+3. **Functional/Standard**: Meets all requirements but lacks 'Craft' (polish, docs, naming).
+4. **Polish/Repo-Compliant**: High quality, full doc updates, passes all local tests.
+5. **State-of-the-Art**: World-class implementation with zero-defect proof and proactive optimizations.
+
+## Core Mandate
+
+You MUST evaluate implementation against **Goal Alignment** and **Pattern Compliance**.
+
+### 1. Goal Alignment (Audit)
+- **Check**: Does the output solve the user's specific request?
+- **Verify**: Cross-reference the `implementation_plan.md`. If any numbered requirement is missing (e.g., "tax reconciliation"), the score MUST be below 3.
+
+### 2. Pattern Compliance (Grounded Evaluation)
+You MUST proactively check for these project-specific requirements:
+- **Financial Logic**: Does every calculation use nullish coalescing or zero-guards? (Pattern: `(val ?? 0)`). If missing, score is < 3.
+- **UI & Layout**: Does the page have a clear L1 focal point according to `composition-theory`?
+- **Naming**: Does it follow `semantics` rules (no generic suffixes like `Helper` or `Utils`)?
+
+## Quality Scale (1-5)
+
+You MUST assign a numeric score (1-5) and a 1-sentence justification for each.
+
+1. **Broken/Dangerous**: Logic errors, security flaws, or incomplete file writes.
+2. **Suboptimal**: Violates key patterns (missing `?? 0`, hardcoded strings, no focal point).
+3. **Acceptable**: Meets functional goals and matches most patterns.
+4. **Professional**: Follows all domain skills and design guidelines; well-documented.
+5. **Exceptional**: Proactively handles edge cases (Skeleton states, error boundaries).
+
+## Evaluation Process
+
+1. **Persona**: Adopt the **Skeptical Critic** mindset.
+2. **Identify**: List all changed files and their associated domain skills.
+3. **Score**: Assign a 1-5 score.
+4. **Critique**: List exactly what is missing or violates patterns.
+5. **Iterate**: Do not consider a task "Done" until scores are >= 4.
+
+## Key Files
+
+| File | Why it matters |
+|------|---------------|
+| `docs/quality-doctrine.md` | The definition of "better" for Skill Graph artifacts |
+| `skills/agent-eval-design/SKILL.md` | Agent, prompt, router, and skill evaluation design |
+| `skills/code-review/SKILL.md` | Diff-level correctness and risk review |
+| `skills/testing-strategy/SKILL.md` | Test planning and verification strategy |
+| `skills/usability-testing/SKILL.md` | UI-specific evaluation gates |
+
+## Reference Files
+- [quality-doctrine](https://github.com/jacob-balslev/skill-graph/blob/main/docs/quality-doctrine.md): The definition of "better."
+- [usability-testing](https://github.com/jacob-balslev/skill-graph/blob/main/skills/usability-testing/SKILL.md): UI-specific evaluation gates.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Scoring >= 4 with missing docs | Violates the completion contract — code alone is never "done" | Check AGENTS.md routing table before scoring |
+| Accepting "tests pass" as full verification | Narrow test success hides missing integration, core-loop, or edge-case coverage | Require evidence of the repo's canonical verification gates |
+| Self-scoring without the Skeptical Critic persona | Agents are systematically optimistic about their own output | Adopt the Critic mindset explicitly before assigning any score |
+| Treating evaluation as code review | Evaluation is holistic quality gating; code review is line-by-line technical analysis | Route technical review to `code-review`, keep evaluation for the completion contract |
+| Skipping financial null-guard checks | Financial logic without `?? 0` guards produces silent NaN/undefined bugs | Always verify nullish coalescing on every financial calculation |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] A numeric 1-5 score was assigned with a 1-sentence justification
+- [ ] All changed files were identified and checked against their domain skills
+- [ ] The implementation plan (if one exists) was cross-referenced for missing requirements
+- [ ] Financial calculations include nullish coalescing guards (`val ?? 0`)
+- [ ] Documentation routing table was checked and required doc updates are included
+- [ ] Linear task has a summary comment if the task has an associated issue
+- [ ] Score is not >= 4 if any requirement from the plan is missing or docs are stale
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Reviewing code for logic bugs, type errors, or security issues | `code-review` | Code review owns the technical review; evaluation owns the holistic quality gate |
+| Evaluating visual design quality or DESIGN_GUIDE compliance | `design-review` | Design review owns the pre/post design quality gates with specific visual checks |
+| Assessing task completion in the multi-agent /manage pipeline | `task-evaluation` | Task-evaluation owns the A/B scoring and pass/fail verdict for automated pipelines |
+| Running a generate-critique-revise self-review loop | `self-evaluation`, `reflection-pattern` | Self-evaluation and reflection own the iterative internal revision cycle |
+| Defining what "better" means for a specific artifact type | `craft-doctrine` | Craft-doctrine defines quality standards; evaluation applies them |

package/marketplace/skills/event-contract-design/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: event-contract-design
+description: "Use when designing or reviewing asynchronous event contracts: producer/consumer ownership, event envelope, schema, topic/channel naming, ordering, idempotency, versioning, compatibility, replay, dead-letter behavior, and AsyncAPI/CloudEvents-style documentation. Do NOT use for domain-event discovery (use `event-storming`), broad interface contracts (use `system-interface-contracts`), inbound provider webhook mechanics (use `webhook-integration`), or HTTP endpoint design (use `api-design`)."
+license: MIT
+compatibility: "Portable async-event contract guidance for queues, streams, pub/sub, internal events, outbound webhooks, and documented event-driven APIs."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"architecture/events\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"event-contract\\\\\\\",\\\\\\\"async-api\\\\\\\",\\\\\\\"cloudevents\\\\\\\",\\\\\\\"event envelope\\\\\\\",\\\\\\\"topic naming\\\\\\\",\\\\\\\"async event schema\\\\\\\",\\\\\\\"event compatibility\\\\\\\",\\\\\\\"replay contract\\\\\\\",\\\\\\\"dead-letter behavior\\\\\\\",\\\\\\\"consumer fixtures\\\\\\\"]\",\"examples\":\"[\\\\\\\"design the event contract for publishing OrderPaid to downstream consumers\\\\\\\",\\\\\\\"define topic names, payload schema, idempotency, and versioning for this event stream\\\\\\\",\\\\\\\"review this outbound webhook event schema before customers integrate with it\\\\\\\",\\\\\\\"write the compatibility rules for consumers of these async messages\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"discover the domain events, commands, and policies in this business process\\\\\\\",\\\\\\\"define every boundary contract between services, jobs, and APIs\\\\\\\",\\\\\\\"verify inbound provider webhook signatures and retry behavior\\\\\\\",\\\\\\\"design REST endpoints, status codes, and pagination\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"event-storming\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-storming discovers domain events and policies; event-contract-design turns selected events into publishable contracts\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"system-interface-contracts owns broad boundary contracts; event-contract-design owns asynchronous message and event surfaces\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"webhook-integration owns inbound third-party delivery mechanics; event-contract-design owns events this system publishes or documents for consumers\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns HTTP resource and action surfaces; event-contract-design owns asynchronous event contracts\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"event-storming\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"observability-modeling\\\\\\\",\\\\\\\"state-machine-modeling\\\\\\\",\\\\\\\"data-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"observability-modeling\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/event-contract-design/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/event-contract-design/SKILL.md
+---
+
+# Event Contract Design
+
+## Coverage
+
+Design asynchronous event contracts for producers and consumers. Covers event envelope, schema, event type, topic/channel naming, producer ownership, consumer expectations, required and optional fields, idempotency keys, ordering, causation and correlation IDs, schema evolution, replay, dead-letter behavior, compatibility, observability, and machine-readable documentation such as AsyncAPI or CloudEvents-style metadata.
+
+## Philosophy
+
+An event is a public promise once another consumer depends on it. If the payload, ordering, retry, or compatibility rules are implicit, every consumer invents its own interpretation and the event stream becomes shared folklore.
+
+Do not confuse event discovery with event contracts. Discovery asks what happened in the domain. Contract design asks what exactly will be published, consumed, replayed, and evolved.
+
+## Method
+
+1. Name the producer, owner, intended consumers, and event purpose.
+2. Separate business event type from transport topic or queue name.
+3. Define envelope fields: id, type, source, time, subject, schema version, correlation, causation, tenant, and idempotency key.
+4. Define payload schema with required, optional, nullable, and deprecated fields.
+5. State ordering, delivery, retry, replay, and dead-letter expectations.
+6. Define compatibility rules: additive fields, breaking changes, versioning, deprecation, and consumer migration.
+7. Add observability fields needed to reconstruct publishing and consumption failures.
+8. Provide at least one positive and one negative contract fixture.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/event-contract-design.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/event-contract-design.json). The checklist below is the authoring gate for async event contracts; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Producer, owner, and consumers are named
+- [ ] Event type, topic/channel, envelope, and payload are distinct
+- [ ] Required, optional, nullable, and deprecated fields are explicit
+- [ ] Idempotency, ordering, retry, replay, and dead-letter behavior are stated
+- [ ] Compatibility rules distinguish additive from breaking changes
+- [ ] Correlation and causation IDs cross async boundaries
+- [ ] Positive and negative fixtures exist for contract testing
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `event-storming` | You are still discovering domain events, commands, policies, aggregates, or timelines. |
+| `system-interface-contracts` | The boundary is not specifically asynchronous events or messages. |
+| `webhook-integration` | You are implementing inbound provider webhooks, signatures, retries, and raw payload handling. |
+| `api-design` | You are designing HTTP endpoints, status codes, pagination, filtering, or error envelopes. |
+| `observability-modeling` | The event contract is settled and the task is telemetry design. |

package/marketplace/skills/event-storming/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: event-storming
+description: "Use when discovering a domain through events, commands, actors, policies, aggregates, read models, external systems, and temporal workflows before implementation. Do NOT use for event schema/topic contracts (use `event-contract-design`), webhook handler implementation (use `webhook-integration`), generic state transition modeling (use `state-machine-modeling`), or persistence schema design (use `data-modeling`)."
+license: MIT
+compatibility: "Portable event-storming discipline for product discovery, domain modeling, event-driven architecture, and workflow analysis."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"architecture/domain-discovery\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"event storming\\\\\\\",\\\\\\\"domain events\\\\\\\",\\\\\\\"commands\\\\\\\",\\\\\\\"aggregates\\\\\\\",\\\\\\\"policies\\\\\\\",\\\\\\\"read models\\\\\\\",\\\\\\\"temporal workflow\\\\\\\",\\\\\\\"event-driven discovery\\\\\\\",\\\\\\\"process modeling\\\\\\\"]\",\"examples\":\"[\\\\\\\"map the order lifecycle as domain events before we design tables or APIs\\\\\\\",\\\\\\\"which commands, policies, and external systems are hidden in this workflow?\\\\\\\",\\\\\\\"use event storming to find aggregate boundaries for fulfillment\\\\\\\",\\\\\\\"turn this incident-prone business process into events and decisions\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement Shopify webhook signature verification and idempotent retries\\\\\\\",\\\\\\\"draw the state machine for this one status field\\\\\\\",\\\\\\\"create a normalized data model and indexes\\\\\\\",\\\\\\\"write event-bus infrastructure code\\\\\\\",\\\\\\\"define the schema, topic, compatibility, and fixtures for a selected event\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-contract-design owns publishable event envelopes, schemas, topics, and compatibility; event-storming discovers the domain behavior before contract design\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"webhook-integration implements inbound provider event handlers; event-storming discovers business-domain events before implementation\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"state-machine-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"state-machine-modeling formalizes states and transitions; event-storming discovers events, commands, policies, and aggregates\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling designs stored data structures after domain events are understood\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design shapes endpoint surfaces; event-storming discovers the domain behavior those surfaces expose\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"bounded-context-mapping\\\\\\\",\\\\\\\"state-machine-modeling\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"conceptual-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"bounded-context-mapping\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/event-storming/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/event-storming/SKILL.md
+---
+
+# Event Storming
+
+## Coverage
+
+Discover domain behavior through temporal events and decisions. Covers domain events, commands, actors, policies, aggregates, read models, external systems, hotspots, timelines, invariants, and handoff into bounded-context, state-machine, data, and API design.
+
+## Philosophy
+
+Event storming starts from "what happened" because events expose real business flow faster than nouns do. Noun-first modeling often freezes premature assumptions. Event-first modeling reveals time, causality, policy, and exceptions.
+
+Do not confuse domain events with technical notifications. "OrderPlaced" is business meaning. "WebhookReceived" is transport detail.
+
+## Method
+
+1. List domain events in past tense.
+2. Place them on a timeline.
+3. Add commands that cause events.
+4. Add actors and external systems that issue commands or receive outcomes.
+5. Add policies: "when event X happens, if condition Y, then command Z."
+6. Identify aggregates that enforce invariants.
+7. Mark hotspots, missing decisions, temporal ambiguity, and unclear ownership.
+8. Hand off to bounded-context, state-machine, data, or API design only after the flow is coherent.
+
+## Verification
+
+- [ ] Events are named in past tense and carry business meaning
+- [ ] Commands are imperative and have actors or policies
+- [ ] Policies are explicit condition-action rules
+- [ ] Aggregates are tied to invariants, not guessed from nouns
+- [ ] External systems and transport details are separated from domain events
+- [ ] Hotspots and unanswered questions are recorded
+- [ ] The timeline can replay a real scenario end to end
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `webhook-integration` | You are implementing provider webhooks, signatures, retries, and deduplication. |
+| `event-contract-design` | You already selected the event and need schema, envelope, topic, compatibility, replay, or fixtures. |
+| `state-machine-modeling` | You already know the lifecycle and need formal states, transitions, and guards. |
+| `data-modeling` | You need tables, keys, indexes, constraints, or data lifecycle. |
+| `api-design` | You need endpoint, request, response, and status-code design. |

package/marketplace/skills/form-ux-architecture/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: form-ux-architecture
+description: "Use when designing or auditing form structure and validation UX: field grouping, required vs optional inputs, validation timing, client/server validation split, submission lifecycle, recovery, multi-step forms, and high-risk data entry. Do NOT use for labels and announcements alone (use `a11y`), validation-message wording (use `microcopy`), API schema design (use `api-design`), or stored data modeling (use `data-modeling`)."
+license: MIT
+compatibility: Portable form UX guidance for web and app forms. Client-side validation improves UX; server-side validation remains mandatory for trust and security.
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/ux\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"form-ux\\\\\\\",\\\\\\\"form architecture\\\\\\\",\\\\\\\"validation timing\\\\\\\",\\\\\\\"client server validation\\\\\\\",\\\\\\\"field grouping\\\\\\\",\\\\\\\"submission lifecycle\\\\\\\",\\\\\\\"form recovery\\\\\\\",\\\\\\\"multi-step forms\\\\\\\",\\\\\\\"required optional fields\\\\\\\",\\\\\\\"empty state design\\\\\\\",\\\\\\\"no results state\\\\\\\"]\",\"examples\":\"[\\\\\\\"design the validation lifecycle for this signup form\\\\\\\",\\\\\\\"audit this checkout form for grouping, required fields, and recovery\\\\\\\",\\\\\\\"should this be one form, a wizard, or progressive disclosure?\\\\\\\",\\\\\\\"split client-side and server-side validation responsibilities for this form\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"add labels so assistive tech can read each field\\\\\\\",\\\\\\\"rewrite the inline validation messages\\\\\\\",\\\\\\\"define the request and response schema for the form submit endpoint\\\\\\\",\\\\\\\"model the database columns that store these inputs\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns labels, focus, fieldsets, errors, and assistive-tech behavior; form-ux-architecture owns form structure and validation lifecycle\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"microcopy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"microcopy owns validation-message wording; form-ux-architecture owns when validation appears and how users recover\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns submit endpoint schemas and error envelopes; form-ux-architecture owns the user-facing input and correction flow\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns stored data shape; form-ux-architecture owns collection and correction before submission\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"task-analysis\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"microcopy\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"microcopy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/form-ux-architecture/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/form-ux-architecture/SKILL.md
+---
+
+# Form UX Architecture
+
+## Coverage
+
+Design form structure and validation behavior. Covers field grouping, labels as structure handoff, required vs optional decisions, progressive disclosure, defaults, input formats, client-side validation, server-side validation, validation timing, submit lifecycle, error recovery, multi-step forms, review steps, autosave, and high-risk data entry.
+
+## Philosophy
+
+Forms are not data dumps. A form is a guided conversation that asks only for information the system truly needs, at the moment the user can answer it, with correction paths that preserve trust.
+
+Client-side validation is a user-experience aid, not a security boundary. The server must validate every submitted field even when the client appears correct.
+
+## Method
+
+1. Name the user goal and the minimum data needed to complete it.
+2. Remove fields that are not needed now or cannot be acted on.
+3. Group fields by user mental model, not database table.
+4. Decide required, optional, defaulted, derived, and deferred fields.
+5. Choose validation timing: on submit, on blur, on change, or after async check.
+6. Split client-side validation from server-side validation and map server errors back to fields.
+7. Define submit, pending, success, failure, retry, and partial-save behavior.
+8. Hand off labels and announcements to `a11y`, wording to `microcopy`, and endpoint shape to `api-design`.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/form-ux-architecture.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/form-ux-architecture.json). The checklist below is the authoring gate for form UX architecture; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Every field has a reason tied to the user's goal or system requirement
+- [ ] Required fields are truly required at this step
+- [ ] Field groups match how users think about the task
+- [ ] Validation timing avoids hostile on-keystroke errors unless immediate feedback is necessary
+- [ ] Client-side checks improve correction speed but do not replace server validation
+- [ ] Server errors map back to fields or a clear form-level recovery path
+- [ ] Submit, pending, success, failure, retry, and partial-save states are defined
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `a11y` | The task is labels, fieldsets, focus, keyboard flow, or screen-reader announcement. |
+| `microcopy` | The task is validation-message wording, placeholder text, button labels, or error copy. |
+| `api-design` | The task is endpoint shape, request/response schema, status codes, or error envelope. |
+| `data-modeling` | The task is persistence schema, constraints, keys, or data lifecycle. |
+| `interaction-feedback` | The task is feedback state staging after the form action starts. |

package/marketplace/skills/framework-fit-analysis/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: framework-fit-analysis
+description: "Use when choosing, replacing, or justifying a framework, library, SDK, runtime, database, UI kit, or platform by fit: constraints, team skill, ecosystem maturity, migration cost, operability, performance, security, and exit cost. Do NOT use for routine dependency hygiene (use `dependency-architecture`), documenting an accepted decision (use `architecture-decision-records`), or framework-specific implementation work."
+license: MIT
+compatibility: "Portable technology-selection discipline for application frameworks, libraries, SDKs, platforms, runtimes, data stores, and agent tooling."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"architecture/technology-selection\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"framework fit\\\\\\\",\\\\\\\"technology selection\\\\\\\",\\\\\\\"library choice\\\\\\\",\\\\\\\"SDK evaluation\\\\\\\",\\\\\\\"platform evaluation\\\\\\\",\\\\\\\"migration cost\\\\\\\",\\\\\\\"exit cost\\\\\\\",\\\\\\\"operability\\\\\\\",\\\\\\\"ecosystem maturity\\\\\\\",\\\\\\\"build vs buy\\\\\\\"]\",\"examples\":\"[\\\\\\\"should we use Next.js server actions, route handlers, or a separate API service for this workflow?\\\\\\\",\\\\\\\"evaluate whether adding this charting library is worth it\\\\\\\",\\\\\\\"compare Supabase, Firebase, and custom Postgres for this project under real constraints\\\\\\\",\\\\\\\"we want to replace this framework - what fit analysis should happen before an ADR?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"audit installed packages for duplication and supply-chain risk\\\\\\\",\\\\\\\"write the ADR after we chose the framework\\\\\\\",\\\\\\\"implement this feature in the framework we already selected\\\\\\\",\\\\\\\"profile a slow page and optimize bottlenecks\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"dependency-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"dependency-architecture governs dependency graph shape and package boundaries; framework-fit-analysis evaluates a candidate technology decision\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"architecture-decision-records\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"architecture-decision-records records accepted decisions; framework-fit-analysis compares options before acceptance\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"performance-engineering measures and optimizes actual behavior; framework-fit-analysis weighs expected performance among selection criteria\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor changes existing code structure; framework-fit-analysis decides whether a larger technology shift is justified\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"architecture-decision-records\\\\\\\",\\\\\\\"dependency-architecture\\\\\\\",\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"owasp-security\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"architecture-decision-records\\\\\\\",\\\\\\\"dependency-architecture\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":180,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/framework-fit-analysis/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/framework-fit-analysis/SKILL.md
+---
+
+# Framework Fit Analysis
+
+## Coverage
+
+Evaluate technology fit before adoption, replacement, or standardization. Covers requirement fit, constraints, ecosystem maturity, maintenance health, team skill, integration cost, migration path, performance envelope, security posture, operational burden, lock-in, exit cost, and decision recording.
+
+## Philosophy
+
+Technology choice is context-dependent. "Best" without constraints is marketing. A good fit analysis makes tradeoffs explicit enough that a team can accept the costs knowingly.
+
+Do not confuse popularity with fit. Do not let a narrow implementation preference choose a durable platform. The right output is a recommendation plus consequences, not a ranking table with fake precision.
+
+## Method
+
+1. State the job the technology must do.
+2. List hard constraints: runtime, hosting, data, compliance, team, budget, timeline.
+3. Define evaluation criteria and weights qualitatively: must-have, important, nice-to-have.
+4. Compare credible options, including staying put.
+5. Assess migration and exit costs.
+6. Identify operational ownership and failure modes.
+7. Recommend one path with accepted tradeoffs.
+8. Hand off to `architecture-decision-records` if the decision is durable.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/framework-fit-analysis.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/framework-fit-analysis.json). The checklist below is the authoring gate for technology-fit decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] The recommendation is tied to explicit project constraints
+- [ ] "Do nothing" or "keep current stack" was considered when real
+- [ ] Migration and exit costs are named
+- [ ] Operational ownership is named
+- [ ] Performance and security claims are evidence-backed or marked uncertain
+- [ ] The decision can be reversed only with known cost
+- [ ] Follow-up ADR is proposed for durable choices
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `dependency-architecture` | You need dependency graph hygiene, package boundaries, duplication control, or supply-chain guardrails. |
+| `architecture-decision-records` | The choice is already made and needs a record. |
+| `performance-engineering` | You need to measure and optimize actual runtime behavior. |
+| A framework-specific skill | The framework is already chosen and the task is implementation. |

package/marketplace/skills/frontend-architecture/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: frontend-architecture
+description: "Use when organizing a frontend codebase — module boundaries, component layering, state ownership, data-flow direction, and the separation between feature code and shared primitives. Do NOT use for visual design decisions, specific framework migration tactics, or backend API contract design."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"frontend architecture\\\\\\\",\\\\\\\"component boundaries\\\\\\\",\\\\\\\"module organization\\\\\\\",\\\\\\\"state management shape\\\\\\\",\\\\\\\"feature-sliced design\\\\\\\",\\\\\\\"container presentational\\\\\\\",\\\\\\\"data flow direction\\\\\\\",\\\\\\\"shared primitives\\\\\\\",\\\\\\\"component layering\\\\\\\",\\\\\\\"frontend folder structure\\\\\\\",\\\\\\\"colocation\\\\\\\",\\\\\\\"Next.js App Router structure\\\\\\\"]\",\"triggers\":\"[\\\\\\\"frontend architecture\\\\\\\",\\\\\\\"component boundaries\\\\\\\",\\\\\\\"folder structure\\\\\\\",\\\\\\\"state shape\\\\\\\",\\\\\\\"where should this code live\\\\\\\"]\",\"examples\":\"[\\\\\\\"Decide whether a new modal lives in the shared component library or inside a feature folder\\\\\\\",\\\\\\\"Reorganize a frontend that has mixed presentational components and data-fetching components in the same files\\\\\\\",\\\\\\\"Choose a state shape that doesn't force every consumer to re-render on unrelated changes\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Pick the brand color palette for a marketing site\\\\\\\",\\\\\\\"Design the REST endpoint shape for the orders resource\\\\\\\",\\\\\\\"Decide whether to use CSS-in-JS or Tailwind\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"design-module-composition\\\\\\\",\\\\\\\"refactor\\\\\\\",\\\\\\\"testing-strategy\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-system-architecture covers token layering, primitive component contracts, and library publishing; this skill covers application-side organization that consumes those primitives.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"API contract shape lives in api-design; this skill takes the API as given and structures the frontend around it.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/frontend-architecture/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/frontend-architecture/SKILL.md
+---
+
+# Frontend Architecture
+
+## Coverage
+Frontend architecture decides three things: where code lives (folder and module structure), what depends on what (allowed import direction), and who owns mutable state (component-local, feature-scoped, or global). This skill covers the common organizing models — feature-sliced (features/<feature>/{ui,model,api}), layered (components/, hooks/, services/, pages/), and domain-driven (domains/<domain>/{ui,logic,data}) — and the trade-offs each makes when the codebase grows from a few features to dozens.
+
+Component layering separates primitives (no business knowledge, configurable purely through props — Button, Input, Stack), composed components (combine primitives with feature-specific layout, still no data fetching — OrderSummary, AddressForm), and connected components (own data fetching, mutation, and routing — OrderDetailPage). The boundary between composed and connected is the most common source of dependency tangles: a "shared" composed component that quietly reaches into a feature-specific store creates a back-edge that breaks the dependency graph.
+
+State shape decisions span four axes: location (component, context, store), normalization (entity-keyed vs. nested), derivation (computed at read time vs. stored), and ownership (who can write). The shape choice determines what re-renders, what stays consistent across views, and what becomes a source of bugs when a mutation forgets to update one of several copies. Server state (data fetched from an API, cache-managed) and client state (UI-only, ephemeral) have different requirements and benefit from being managed by different tools.
+
+Import direction enforces the architecture. A rule like "shared/ may not import from features/, and feature A may not import from feature B" is checkable with ESLint boundary plugins and tells the team at PR time when a change crosses an intended layer. Without enforcement, the structure degrades within months — a single shortcut import becomes the norm.
+
+## Philosophy
+The folder structure is not the architecture; the import graph is. A pretty folder tree with cyclic imports between features is architecturally worse than a flat folder with strict one-way dependencies. Optimize for "where would I look for this" (colocation by feature) and "what changes together stays together" (cohesion) over imposed taxonomy.
+
+Server state and client state are different problems. Mixing them in a single store creates cache-invalidation bugs that look like rendering bugs. Use the same tool for fetching, caching, and revalidating server data; reserve global client state for genuinely cross-cutting UI concerns (theme, current user, route).
+
+## Verification
+- An import-boundary linter is configured and a CI step fails the build on violations.
+- Every feature folder can be removed without touching code outside it, except a single registration point (route table, feature flag map).
+- A new developer can name where any given piece of code lives within thirty seconds of being told the feature name and the kind of thing (UI vs. data vs. logic).
+- Server state is fetched through one mechanism (a single query/cache library) — counting fetch call sites in client code returns approximately the number of distinct endpoints, not multiples per endpoint.
+- Component props for shared primitives contain no feature-specific names; a grep for feature names in shared/ returns nothing.
+- Re-render counts on a representative interaction can be measured and explained — no "this component re-renders five times and I'm not sure why."
+- Tests follow the layering: primitives tested in isolation, connected components tested with mocked data layer, no test reaches across feature boundaries.
+
+## Do NOT Use When
+- The decision is visual rather than structural — color, type, spacing, motion. Use visual-design-foundations, color-system-design, or typography-system.
+- The work is publishing or versioning a shared component library across multiple applications. Use design-system-architecture.
+- The task is choosing or migrating a specific framework (React→Solid, Webpack→Vite). This skill is framework-neutral.
+- You are designing the API the frontend consumes. Use api-design or system-interface-contracts.
+- The problem is a single component's internal behavior or accessibility. Use design-module-composition, interaction-patterns, or a11y.