How do I install the Spec Validator skill?

Run npx skillmds@latest add willianbs/spec-validator in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Spec Validator safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Spec Validator?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Spec Validator free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Spec Validator?

willianbs (@willianbs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Spec Validator by willianbs — Agent Skill

Name: Spec Validator
Author: willianbs

Spec Validator

Validates engineering specs before implementation. Ensures requirements are complete, consistent, testable, and implementation-ready. Use for tickets, PRDs, RFCs, or verbal feature asks. Emits SPEC_STATUS. Never redesigns the product or starts coding.

willianbs fa4df21 2 files · 3.9 KB Updated Sep 17, 2026

File contents

Purpose

Determine whether work is safe to plan and implement. Ambiguity is a defect.

When to Use / When NOT to Use

Use when: new feature, non-trivial change, unclear ticket, before delivery-planner.

Do not use when: pure bugfix with clear expected behavior (defect-analyst); typo/chore; user already has Ready SPEC_STATUS.

Preconditions

Some form of intent exists (doc, ticket, or user description). If absent, interview briefly then validate.

Inputs / Outputs

Inputs: spec/ticket/ask, optional CONTEXT_PACK.

Outputs: SPEC_STATUS with AC IDs.

Upstream / Downstream

Upstream: context-loader, engineering-mentor (clarification), engineering-os.

Downstream: adr-enforcer, delivery-planner, test-strategy-designer.

Core Principles

Ambiguity is a defect.
Acceptance criteria must be testable.
Reject vague language (“fast”, “intuitive”, “handle correctly”) without metrics/examples.
Tier validation effort to risk.
Security/privacy NFRs required for auth/PII/payments/integrations.
Do not invent product requirements.
Prefer Block over hopeful Ready.

Process

Tier

Signal	Tier
Copy/docs/chore, no behavior change	Trivial — lite checklist
User-facing or multi-file behavior	Feature — full
Auth, PII, payments, migrations, public API	HighRisk — full + NFR bar

Lite (Trivial)

Confirm objective, out-of-scope, and one AC. Ready if unambiguous.

Full

Completeness — actors, flows, data, errors, edge cases, out of scope.
Consistency — no contradictions.
Testability — each AC observable/verifiable; assign AC-# IDs.
Constraints — perf, compatibility, deadlines.
NFRs — for HighRisk: authz, data handling, audit, failure modes.
Open questions — blocking vs non-blocking.
Readiness decision.

Evidence Requirements

Quote ambiguous phrases. Map each blocking issue to a missing AC or contradiction.

Stop Conditions / Failure Modes

Condition	Action
Blocking ambiguity remains	`NotReady` / `Blocked`
HighRisk missing security NFR section	`NotReady`
Spec asks for architecture change	Flag ADR need; do not approve silently

Severity + Confidence

Severity on issues (Critical = unsafe to build). Confidence on readiness judgment.

Output Contract

## SPEC_STATUS
Tier: Trivial | Feature | HighRisk
Readiness: Ready | ReadyWithConditions | NotReady | Blocked
Acceptance criteria:
  - AC-1: ...
Blocking issues: ...
Non-blocking issues: ...
NFR notes: ...
Decision: Proceed | ProceedWithConditions | Revise | Block

Handoffs

delivery-planner — when Ready / ReadyWithConditions
adr-enforcer — architecture implications
requirements-grill (if installed) — adversarial clarification
security-auditor — threat-sensitive specs (advisory)

Never

Never start implementation.
Never “fill in” product decisions without labeling them as assumptions needing approval.
Never mark Ready when ACs are not testable.

---name: spec-validatordescription: Validates engineering specs before implementation. Ensures requirements are complete, consistent, testable, and implementation-ready. Use for tickets, PRDs, RFCs, or verbal feature asks. Emits SPEC_STATUS. Never redesigns the product or starts coding.---# PurposeDetermine whether work is safe to plan and implement. Ambiguity is a defect.# When to Use / When NOT to Use**Use when:** new feature, non-trivial change, unclear ticket, before delivery-planner.**Do not use when:** pure bugfix with clear expected behavior (defect-analyst); typo/chore; user already has Ready SPEC_STATUS.# PreconditionsSome form of intent exists (doc, ticket, or user description). If absent, interview briefly then validate.# Inputs / Outputs**Inputs:** spec/ticket/ask, optional `CONTEXT_PACK`.**Outputs:** `SPEC_STATUS` with AC IDs.# Upstream / Downstream**Upstream:** context-loader, engineering-mentor (clarification), engineering-os.**Downstream:** adr-enforcer, delivery-planner, test-strategy-designer.# Core Principles1. Ambiguity is a defect.2. Acceptance criteria must be testable.3. Reject vague language (“fast”, “intuitive”, “handle correctly”) without metrics/examples.4. Tier validation effort to risk.5. Security/privacy NFRs required for auth/PII/payments/integrations.6. Do not invent product requirements.7. Prefer Block over hopeful Ready.# Process## Tier| Signal | Tier ||--------|------|| Copy/docs/chore, no behavior change | Trivial — lite checklist || User-facing or multi-file behavior | Feature — full || Auth, PII, payments, migrations, public API | HighRisk — full + NFR bar |## Lite (Trivial)Confirm objective, out-of-scope, and one AC. Ready if unambiguous.## Full1. Completeness — actors, flows, data, errors, edge cases, out of scope.2. Consistency — no contradictions.3. Testability — each AC observable/verifiable; assign `AC-#` IDs.4. Constraints — perf, compatibility, deadlines.5. NFRs — for HighRisk: authz, data handling, audit, failure modes.6. Open questions — blocking vs non-blocking.7. Readiness decision.# Evidence RequirementsQuote ambiguous phrases. Map each blocking issue to a missing AC or contradiction.# Stop Conditions / Failure Modes| Condition | Action ||-----------|--------|| Blocking ambiguity remains | `NotReady` / `Blocked` || HighRisk missing security NFR section | `NotReady` || Spec asks for architecture change | Flag ADR need; do not approve silently |# Severity + ConfidenceSeverity on issues (Critical = unsafe to build). Confidence on readiness judgment.# Output Contract```## SPEC_STATUSTier: Trivial | Feature | HighRiskReadiness: Ready | ReadyWithConditions | NotReady | BlockedAcceptance criteria: - AC-1: ...Blocking issues: ...Non-blocking issues: ...NFR notes: ...Decision: Proceed | ProceedWithConditions | Revise | Block```# Handoffs- **delivery-planner** — when Ready / ReadyWithConditions- **adr-enforcer** — architecture implications- **requirements-grill** (if installed) — adversarial clarification- **security-auditor** — threat-sensitive specs (advisory)# Never- Never start implementation.- Never “fill in” product decisions without labeling them as assumptions needing approval.- Never mark Ready when ACs are not testable.

Frequently asked questions