spec-grounded-design
Skill1 starsChanged 5 months agoMITView on GitHub
Before implementing against any protocol, SDK, or external API, ground the design in reality — pull the actual spec, probe the live endpoint to capture how it really behaves, reconcile spec-vs-reality (reality wins), and extract a design contract of verified facts, edge cases, and invariants to build against. Encodes "read the protocol" + "test live before assuming the spec is correct," because reverse-engineered or stale docs lag the real API. Triggers on "integrate with X", "design against this API", "read the protocol first", "before we build this integration", "is the spec right", "how does this API actually behave", "ground this in the docs", "verify before coding". Use before writing integration code against an external system, not for internal logic.
In this repository51 other files it gives its agents.
- architect-enterprise-aiSkill
- author-agent-skillsSkill
- build-agent-harnessesSkill
- build-aiewf-2024-ragSkill
- build-generative-mediaSkill
- build-multimodal-productsSkill
- build-rag-search-stacksSkill
- build-robotics-aiSkill
- build-with-deepmindSkill
- build-with-microsoft-aiSkill
- build-with-openaiSkill
- deploy-public-sector-aiSkill
- design-agent-skillsSkill
- evaluate-with-braintrustSkill
- lead-ai-engineering-teamsSkill
- lead-ai-transformationSkill
- learn-summit-2023-remoteSkill
- learn-summit-2023-talksSkill
- navigate-aie-europe-2026Skill
- navigate-aiewf-2024-keynotesSkill
- observe-ai-productionSkill
- operate-agent-memorySkill
- operate-legal-ai-agentsSkill
- operate-openclaw-agentsSkill
- optimize-llm-inferenceSkill
- plan-sovereign-aiSkill
- price-ai-productsSkill
- run-aiewf-2024-evalsSkill
- run-llm-evalsSkill
- run-summit-2023-workshopsSkill
- secure-ai-agentsSkill
- ship-ai-as-pmSkill
- ship-aiewf-2024-agentsSkill
- train-llms-locallySkill
- architecture-reviewSkill
- chat-failure-auditSkill
- create-a-skillSkill
- cross-model-reviewSkill
- cto-weekly-reviewSkill
- friction-auditSkill
- ig-carouselSkill
- pdf-reportSkill
- raise-prSkill
- reel-editSkill
- research-reportSkill
- ship-checkSkill
- state-lifetime-decisionSkill
- ste100Skill
- scroll-engineeringSkill
- ui-uxSkill
- verify-like-a-userSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Don't code an integration from memory or from docs you assume are right.
- Very specific: line 61
Read grounding-checklist.md.
- Distinctive: line 82
If the probe contradicts a core assumption the feature depended on, surface that now — it may change the design or the feasibility before a …
- Very specific: line 106
Do not implement here — the contract is the input to a separate, confirmed build step (pair with architecture-review if the probe revealed …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec-Grounded Design
Don't code an integration from memory or from docs you assume are right. Get the real spec, probe the real behavior, treat reality as truth, then design against a contract. Reverse-engineered and stale specs lag the live API — the live probe is non-negotiable.
Works with any agent that can fetch docs and run a shell. No vendor APIs of its own.
Supporting files (read when needed):
- grounding-checklist.md — what to verify live, probe patterns, reality-wins rule
- design-contract-template.md — the contract output format
Output: {SKILL_OUTPUT_DIR}/spec-grounded-design/ — see ../OUTPUT.md
Step 0 — Scope the integration
Establish (ask only if missing):
- The target — which protocol / SDK / API, and which version or endpoint.
- What you need from it — the specific operations the feature requires (not the whole surface — ground what you'll actually use).
- Probe access — is there a sandbox/test key/local instance to hit safely? If the only instance is production, see the edge cases (read-only, never mutate prod to "test").
Resolve output dir per ../OUTPUT.md. Default ./skill-outputs/spec-grounded-design/.
Step 1 — Pull the primary source
Fetch the actual spec — the protocol document, the official API reference, the SDK's typed source — not a blog, not memory, not a summary. Record the version and the URL.
For each operation you need, capture from the spec: the request shape, the response shape, auth, error codes, pagination, rate limits, and anything stateful (sessions, cursors, idempotency keys).
Note where the spec is vague or silent — those are exactly the spots the live probe will resolve.
Step 2 — Probe the live behavior (non-negotiable)
Read grounding-checklist.md. Hit the real endpoint with the
smallest possible request — curl or a tiny script — and capture what actually
happens, not what the spec says should:
- Real response shape and field names (casing, nesting, nulls).
- Real error behavior — force a 401/404/429 and see the actual body and headers.
- Real stateful behavior — session lifetime, what a dropped session returns, cursor format.
- Real edge cases — empty results, large payloads, the silent defaults.
Read the probe output before writing any code. This is the step that catches the spec-vs-reality gap. Show the user the raw probe result.
Step 3 — Reconcile: reality wins
Diff the spec against the probe. For every difference, the live behavior is the truth and the spec is wrong/stale. Record each delta explicitly:
SPEC says X · REALITY is Y · DESIGN against Y.
If the probe contradicts a core assumption the feature depended on, surface that now — it may change the design or the feasibility before a line of code is written.
Step 4 — Write the design contract
Fill in design-contract-template.md: the verified facts per operation, the spec-vs-reality deltas, the edge cases the code must handle, and the invariants the implementation must preserve (e.g. "a dropped session returns 404 → re-initialize, do not reauth"). This contract is what you implement against and test against.
Save it to the output dir; update index.md.
Step 5 — Output to user
- The path to the saved contract.
- The 1–3 most important spec-vs-reality deltas — the things that would have caused bugs.
- The invariants the implementation must hold.
- A go / caution call: is the integration as expected, or did the probe surface something that changes the plan?
- Do not implement here — the contract is the input to a separate, confirmed build step
(pair with
architecture-reviewif the probe revealed a real fork).
Edge cases
- No sandbox, only production — probe read-only (GET/list), never mutate prod to "test." If you must verify a write path, ask the user for a safe test tenant.
- Auth blocks the probe — get a scoped test credential from the user; don't skip the probe and design blind. A blind design is the failure mode this skill exists to prevent.
- Spec and reality agree everywhere — great; record that the contract is spec-verified and move on. The probe still paid for itself.
- The API is undocumented — the probe is the spec; be extra thorough on errors and edge cases, and mark the contract "reverse-engineered, verify on upgrades."
- Secrets — never write keys/tokens into the contract or the saved output; reference them by name.
Invocation examples
@spec-grounded-design we're integrating the MCP streamable-HTTP transport — read the protocol and verify before we build
design against the Stripe subscriptions API — is the spec right?
how does this API actually behave on an expired session? probe it first
ground this OAuth flow in the real endpoint before I write the client
verify the pagination behavior live before we design the syncDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

