{"slug":"addyosmani-spec-driven-development","name":"spec-driven-development","description":"Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.","long_description":"---\nname: spec-driven-development\ndescription: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.\n---\n\n# Spec-Driven Development\n\n## Overview\n\nWrite a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.\n\n## When to Use\n\n- Starting a new project or feature\n- Requirements are ambiguous or incomplete\n- The change touches multiple files or modules\n- You're about to make an architectural decision\n- The task would take more than 30 minutes to implement\n\n**When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.\n\n## The Gated Workflow\n\nSpec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.\n\n```\nSPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT\n   │          │        │          │\n   ▼          ▼        ▼          ▼\n Human      Human    Human      Human\n reviews    reviews  reviews    reviews\n```\n\n### Phase 0: Scope Check\n\nMost requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.\n\n**Detection.** Decompose before specifying when a single requirement bundles several independently testable capabilities:\n\n- The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting)\n- Acceptance criteria cluster into groups that could ship and be verified separately\n- One capability could be cut or replaced without rewriting the others' requirements\n\n**Propose a capability map before writing any spec.** Small and reviewable — a module table plus a build order, not a project plan:\n\n```markdown\n# Capability Map: [Initiative Name]\n\n| Module id | Responsibility | Depends on |\n|---|---|---|\n| identity | Accounts, sessions, SSO | — |\n| billing | Plans, invoices, payments | identity |\n| notifications | Email and webhook fan-out | identity |\n| reporting | Usage dashboards | billing, notifications |\n\nBuild order: identity → billing, notifications → reporting\n```\n\n- **Stable module ids.** Kebab-case, chosen once, never renamed mid-initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active.\n- **Dependency direction, no cycles.** Arrows point one way. If two modules each need the other, they are one module.\n- **Interfaces live at the boundary.** The map records that `billing` depends on `identity`; the contract between them belongs in the provider module's spec (see `api-and-interface-design` for designing it).\n\n**The map is gated like every phase.** The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not.\n\n**Then recurse per module.** Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map at the project root and each module's spec alongside it, named by module id (`SPEC-identity.md`, `SPEC-billing.md`) — the map, not filename guessing, is the index of what exists.\n\n### Phase 1: Specify\n\nStart with a high-level vision. Ask the human clarifying questions until requirements are concrete.\n\n**Surface assumptions immediately.** Before writing any spec content, list what you're assuming:\n\n```\nASSUMPTIONS I'M MAKING:\n1. This is a web application (not native mobile)\n2. Authentication uses session-based cookies (not JWT)\n3. The database is PostgreSQL (based on existing Prisma schema)\n4. We're targeting modern browsers only (no IE11)\n→ Correct me now or I'll proceed with these.\n```\n\nDon't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding.\n\n**Write a spec document covering these six core areas:**\n\n1. **Objective** — What are we building and why? Who is the user? What does success look like?\n\n2. **Commands** — Full executable commands with flags, not just tool names.\n   ```\n   Build: npm run build\n   Test: npm test -- --coverage\n   Lint: npm run lint --fix\n   Dev: npm run dev\n   ```\n\n3. **Project Structure** — Where source code lives, where tests go, where docs belong.\n   ```\n   src/           → Application source code\n   src/components → React components\n   src/lib        → Shared utilities\n   tests/         → Unit and integration tests\n   e2e/           → End-to-end tests\n   docs/          → Documentation\n   ```\n\n4. **Code Style** — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.\n\n5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns.\n\n6. **Boundaries** — Three-tier system:\n   - **Always do:** Run tests before commits, follow naming conventions, validate inputs\n   - **Ask first:** Database schema changes, adding dependencies, changing CI config\n   - **Never do:** Commit secrets, edit vendor directories, remove failing tests without approval\n\n**Spec template:**\n\n```markdown\n# Spec: [Project/Feature Name]\n\n## Objective\n[What we're building and why. User stories or acceptance criteria.]\n\n## Tech Stack\n[Framework, language, key dependencies with versions]\n\n## Commands\n[Build, test, lint, dev — full commands]\n\n## Project Structure\n[Directory layout with descriptions]\n\n## Code Style\n[Example snippet + key conventions]\n\n## Testing Strategy\n[Framework, test locations, coverage requirements, test levels]\n\n## Boundaries\n- Always: [...]\n- Ask first: [...]\n- Never: [...]\n\n## Success Criteria\n[How we'll know this is done — specific, testable conditions]\n\n## Open Questions\n[Anything unresolved that needs human input]\n```\n\n**Reframe instructions as success criteria.** When receiving vague requirements, translate them into concrete conditions:\n\n```\nREQUIREMENT: \"Make the dashboard faster\"\n\nREFRAMED SUCCESS CRITERIA:\n- Dashboard LCP < 2.5s on 4G connection\n- Initial data load completes in < 500ms\n- No layout shift during load (CLS < 0.1)\n→ Are these the right targets?\n```\n\nThis lets you loop, retry, and problem-solve toward a clear goal rather than guessing what \"faster\" means.\n\n### Phase 2: Plan\n\nWith the validated spec, generate a technical implementation plan:\n\n1. Identify the major components and their dependencies\n2. Determine the implementation order (what must be built first)\n3. Note risks and mitigation strategies\n4. Identify what can be built in parallel vs. what must be sequential\n5. Define verification checkpoints between phases\n\n> Follow `planning-and-task-breakdown` for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, `planning-and-task-breakdown` takes precedence.\n>\n> **Output convention:** Save the plan to `tasks/plan.md` and record the task list in the task list target defined by `planning-and-task-breakdown` (default `tasks/todo.md`; projects may designate an external tracker instead). Create `tasks/` if it does not exist. Downstream commands (`/build`, etc.) expect these defaults.\n\nThe plan should be reviewable: the human should be able to read it and say \"yes, that's the right approach\" or \"no, change X.\"\n\n### Phase 3: Tasks\n\nBreak the plan into discrete, implementable tasks:\n\n- Each task should be completable in a single focused session\n- Each task has explicit acceptance criteria\n- Each task includes a verification step (test, build, manual check)\n- Tasks are ordered by dependency, not by perceived importance\n- No task should require changing more than ~5 files\n\n> Follow `planning-and-task-breakdown` for the full task-sizing and dependency-ordering mechanics; it is the canonical source. The template below is a lightweight inline form; if they ever diverge, `planning-and-task-breakdown` takes precedence.\n\n**Task template:**\n```markdown\n- [ ] Task: [Description]\n  - Acceptance: [What must be true when done]\n  - Verify: [How to confirm — test command, build, manual check]\n  - Files: [Which files will be touched]\n```\n\n### Phase 4: Implement\n\nExecute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.\n\n## Keeping the Spec Alive\n\nThe spec is a living document, not a one-time artifact:\n\n- **Update when decisions change** — If you discover the data model needs to change, update the spec first, then implement.\n- **Update when scope changes** — Features added or cut should be reflected in the spec.\n- **Commit the spec** — The spec belongs in version control alongside the code.\n- **Reference the spec in PRs** — Link back to the spec section that each PR implements.\n\n## Common Rationalizations\n\n| Rationalization | Reality |\n|---|---|\n| \"This is simple, I don't need a spec\" | Simple tasks don't need *long* specs, but they still need acceptance criteria. A two-line spec is fine. |\n| \"I'll write the spec after I code it\" | That's documentation, not specification. The spec's value is in forcing clarity *before* code. |\n| \"The spec will slow us down\" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |\n| \"Requirements will change anyway\" | That's why the spec is a living document. An outdated spec is still better than no spec. |\n| \"The user knows what they want\" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |\n| \"It's one big feature; splitting it is overhead\" | If acceptance criteria cluster into independently testable groups, a monolithic spec forces every downstream task to reason over the whole contract. A ten-line capability map is the cheap alternative. |\n| \"I'll decompose during planning\" | Planning slices tasks within a spec. By then the oversized artifact already exists — module boundaries and dependency direction must be decided before the spec is written, not after. |\n\n## Red Flags\n\n- Starting to write code without any written requirements\n- Asking \"should I just start building?\" before clarifying what \"done\" means\n- Implementing features not mentioned in any spec or task list\n- Making architectural decisions without documenting them\n- Skipping the spec because \"it's obvious what to build\"\n- One spec whose requirements span several independently testable capabilities\n- Module boundaries or build order decided implicitly during implementation because no capability map was approved up front\n\n## Verification\n\nBefore proceeding to implementation, confirm:\n\n- [ ] The spec covers all six core areas\n- [ ] The human has reviewed and approved the spec\n- [ ] Success criteria are specific and testable\n- [ ] Boundaries (Always/Ask First/Never) are defined\n- [ ] The spec is saved to a file in the repository\n- [ ] If the request bundles several independently testable capabilities, a capability map (module ids, dependency direction, build order) was approved before any module spec was written\n- [","tagline":"Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabiliti","category":"research","tags":["agent-skill"],"author":"addyosmani","verified":false,"attribution":{"status":"registry_indexed","statusLabel":"Registry indexed","shortLabel":"REGISTRY INDEXED","sourceLabel":"recursive skill source sync","sourceDetail":"addyosmani/agent-skills","creatorName":"addyosmani","creatorUrl":"https://github.com/addyosmani","sourceUrl":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","indexedBy":"OpenAgentSkill community index","claimUrl":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development#claim-this-skill","claimCta":"Claim this skill","trustNote":"This listing was indexed from public sources and is not marked official until a maintainer claim is approved.","publicNote":"Attribution links to the public repository or creator profile. Creators can claim the listing to update ownership signals."},"stats":{"stars":92201,"forks":9827,"verified_installs":0,"successful_runs":0,"total_outcomes":0,"rating":0,"review_count":0,"quality_score":58.3},"quality":{"score":95,"tier":"excellent","label":"Excellent","summary":"High-confidence pick with strong adoption and healthy maintenance signals.","signals":[{"label":"GitHub stars","value":"92K","tone":"positive"},{"label":"Freshness","value":"2d ago","tone":"positive"},{"label":"Install ready","value":"Yes","tone":"positive"},{"label":"License","value":"MIT","tone":"neutral"}],"warnings":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions."]},"trust":{"version":"trust-score-v5","score":72,"base_score":80,"outcome_confidence":0,"tier":"review","label":"Sandbox only","summary":"Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.","recommendedAction":"Run only in a sandbox and compare close alternatives before using it for real work.","decision":{"install_policy":"human_review_before_install","auto_install_allowed":false,"human_review_required":true,"sandbox_first":true,"agent_action":"Compare alternatives before installing.","reasoning":["72/100 Trust Score v5","80/100 Trust Score v4 baseline","Needs more real agent outcomes before unattended install","Install path is available","Review before production"],"review_required_when":["The workspace contains production secrets, payments, private customer data, or irreversible actions.","The install command requests shell, network, credential, database, or broad filesystem access.","Outcome evidence is missing, recently failed, or required human review.","Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"]},"dimensions":[{"id":"github_adoption","label":"GitHub adoption","score":100,"weight":0.13,"status":"pass","detail":"92K GitHub stars"},{"id":"repo_activity","label":"Stars/forks activity","score":100,"weight":0.08,"status":"pass","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"id":"maintenance","label":"Recent maintenance","score":100,"weight":0.14,"status":"pass","detail":"2d since push"},{"id":"license","label":"License clarity","score":86,"weight":0.09,"status":"pass","detail":"MIT"},{"id":"documentation","label":"README/SKILL.md completeness","score":86,"weight":0.14,"status":"pass","detail":"Metadata includes enough usage and workflow context"},{"id":"dependency_risk","label":"Dependency/runtime risk","score":74,"weight":0.12,"status":"info","detail":"network or browser surface, database surface"},{"id":"installability","label":"Install availability","score":92,"weight":0.1,"status":"pass","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"id":"install_safety","label":"Install command safety","score":92,"weight":0.1,"status":"pass","detail":"standard package or runtime install path"},{"id":"permission_surface","label":"Permission surface","score":36,"weight":0.07,"status":"fail","detail":"shell or command execution, filesystem or document access"},{"id":"repository","label":"Repository evidence","score":86,"weight":0.04,"status":"pass","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"id":"review_status","label":"Review status","score":66,"weight":0.05,"status":"info","detail":"AI review data available"},{"id":"agent_outcomes","label":"Agent Proven outcomes","score":54,"weight":0.13,"status":"info","detail":"No agent outcome data yet"}],"checks":[{"status":"pass","label":"GitHub adoption","detail":"92K GitHub stars"},{"status":"pass","label":"Stars/forks activity","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"status":"pass","label":"Recent maintenance","detail":"2d since push"},{"status":"pass","label":"License clarity","detail":"MIT"},{"status":"pass","label":"README/SKILL.md completeness","detail":"Metadata includes enough usage and workflow context"},{"status":"info","label":"Dependency/runtime risk","detail":"network or browser surface, database surface"},{"status":"pass","label":"Install availability","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"status":"pass","label":"Install command safety","detail":"standard package or runtime install path"},{"status":"fail","label":"Permission surface","detail":"shell or command execution, filesystem or document access"},{"status":"pass","label":"Repository evidence","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"status":"info","label":"Review status","detail":"AI review data available"},{"status":"info","label":"Agent Proven outcomes","detail":"No agent outcome data yet"},{"status":"warn","label":"Ownership","detail":"No approved owner claim yet"},{"status":"pass","label":"OpenAgentSkill usage","detail":"2 views, 0 install copies"},{"status":"info","label":"Agent outcomes","detail":"No agent outcome data yet"}],"strengths":["AI review approved","Install path is available","Repository evidence is available","Recently maintained repository","Large GitHub adoption signal","Install command has no obvious high-risk pattern","Outcome loop is ready but needs first real agent run"],"warnings":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access","No real agent outcome reports yet","Human review required before unattended installation"],"evidence":{"stars":"92K GitHub stars","repoActivity":"92K stars, 9.8K forks","lastPushed":"2d since push","license":"MIT","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","installSafety":"standard package or runtime install path","permissionSurface":"shell or command execution, filesystem or document access","documentation":"Strong README/SKILL.md context","agentOutcomes":"No agent outcome data yet","agentProvenScore":0,"outcomeConfidence":"0%","installPolicy":"human_review_before_install"},"installReadiness":{"ready":true,"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","policy":"human_review_before_install","label":"Human review before install","notes":["Install path is available","Repository evidence is available","License is declared","No Agent Proven outcome evidence yet","2d since push","Trust Score v5 requires review or sandbox-only use before install."]},"agentCompatibility":["Codex","Claude Code","Cursor","OpenAgentSkill CLI"],"riskSummary":{"level":"medium","label":"Review before production","notes":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"outcomeEvidence":{"total":0,"successes":0,"failures":0,"notRelevant":0,"successRate":null,"installAttempts":0,"riskBlocked":0,"setupRequired":0,"installSuccessRate":null,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"recentSuccessRate":null,"recentFailureRate":null,"uniqueAgents":0,"agentProvenScore":0,"agentProvenLabel":"Needs first agent run","lastOutcomeAt":null,"label":"No agent outcome data yet"},"autoInstall":{"allowed":false,"sandboxRequired":true,"policy":"human_review_before_install","reason":"Compare alternatives before installing."},"outcome_loop":{"version":"openagentskill-agent-outcome-v4","required_after_install":true,"endpoint":"/api/agent/outcome","method":"POST","event_id_source":"feedback.event_id, install_receipt.resolve_event_id, or decision_packet.outcome_feedback.event_id","expected_outcomes":["success","failed","not_relevant","blocked_by_risk","setup_required"],"required_fields":["event_id","skill_slug","task"],"quality_fields":["task_success","output_quality","error_type","human_review_required","used_in_production","workspace","evidence_url","time_to_useful_ms","source_version"],"ranking_inputs_updated":["Trust Score v5 outcome confidence","Agent Proven Score","Resolve ranking task-fit evidence","Skill detail machine-readable metadata","Outcome leaderboard"]},"agent_contract":{"suited_tasks":["research","agent-skill"],"suited_agents":["Codex","Claude Code","Cursor","OpenAgentSkill CLI"],"install_command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","trust_score":72,"trust_version":"trust-score-v5","risk_level":"medium","do_not_use_when":["Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"],"before_install":["Read the audit page and machine-readable metadata.","Confirm the install command, license, and permission surface fit the workspace.","Get explicit human approval or choose an alternative before installing."],"after_run":["Report the outcome to /api/agent/outcome using the resolve event id.","Include output_quality, workspace, human_review_required, and evidence_url when available.","Re-resolve before broad production rollout."]},"bestFor":["research","agent-skill"],"doNotUseFor":["Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"],"knownRisks":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"],"backward_compatible":{"trust_score_v4":{"version":"trust-score-v4","score":80,"tier":"strong","label":"Strong shortlist","summary":"Good trust signals with a few areas worth checking before rollout."}}},"trust_score_v5":{"version":"trust-score-v5","score":72,"base_score":80,"outcome_confidence":0,"tier":"review","label":"Sandbox only","summary":"Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.","recommendedAction":"Run only in a sandbox and compare close alternatives before using it for real work.","decision":{"install_policy":"human_review_before_install","auto_install_allowed":false,"human_review_required":true,"sandbox_first":true,"agent_action":"Compare alternatives before installing.","reasoning":["72/100 Trust Score v5","80/100 Trust Score v4 baseline","Needs more real agent outcomes before unattended install","Install path is available","Review before production"],"review_required_when":["The workspace contains production secrets, payments, private customer data, or irreversible actions.","The install command requests shell, network, credential, database, or broad filesystem access.","Outcome evidence is missing, recently failed, or required human review.","Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"]},"dimensions":[{"id":"github_adoption","label":"GitHub adoption","score":100,"weight":0.13,"status":"pass","detail":"92K GitHub stars"},{"id":"repo_activity","label":"Stars/forks activity","score":100,"weight":0.08,"status":"pass","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"id":"maintenance","label":"Recent maintenance","score":100,"weight":0.14,"status":"pass","detail":"2d since push"},{"id":"license","label":"License clarity","score":86,"weight":0.09,"status":"pass","detail":"MIT"},{"id":"documentation","label":"README/SKILL.md completeness","score":86,"weight":0.14,"status":"pass","detail":"Metadata includes enough usage and workflow context"},{"id":"dependency_risk","label":"Dependency/runtime risk","score":74,"weight":0.12,"status":"info","detail":"network or browser surface, database surface"},{"id":"installability","label":"Install availability","score":92,"weight":0.1,"status":"pass","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"id":"install_safety","label":"Install command safety","score":92,"weight":0.1,"status":"pass","detail":"standard package or runtime install path"},{"id":"permission_surface","label":"Permission surface","score":36,"weight":0.07,"status":"fail","detail":"shell or command execution, filesystem or document access"},{"id":"repository","label":"Repository evidence","score":86,"weight":0.04,"status":"pass","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"id":"review_status","label":"Review status","score":66,"weight":0.05,"status":"info","detail":"AI review data available"},{"id":"agent_outcomes","label":"Agent Proven outcomes","score":54,"weight":0.13,"status":"info","detail":"No agent outcome data yet"}],"checks":[{"status":"pass","label":"GitHub adoption","detail":"92K GitHub stars"},{"status":"pass","label":"Stars/forks activity","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"status":"pass","label":"Recent maintenance","detail":"2d since push"},{"status":"pass","label":"License clarity","detail":"MIT"},{"status":"pass","label":"README/SKILL.md completeness","detail":"Metadata includes enough usage and workflow context"},{"status":"info","label":"Dependency/runtime risk","detail":"network or browser surface, database surface"},{"status":"pass","label":"Install availability","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"status":"pass","label":"Install command safety","detail":"standard package or runtime install path"},{"status":"fail","label":"Permission surface","detail":"shell or command execution, filesystem or document access"},{"status":"pass","label":"Repository evidence","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"status":"info","label":"Review status","detail":"AI review data available"},{"status":"info","label":"Agent Proven outcomes","detail":"No agent outcome data yet"},{"status":"warn","label":"Ownership","detail":"No approved owner claim yet"},{"status":"pass","label":"OpenAgentSkill usage","detail":"2 views, 0 install copies"},{"status":"info","label":"Agent outcomes","detail":"No agent outcome data yet"}],"strengths":["AI review approved","Install path is available","Repository evidence is available","Recently maintained repository","Large GitHub adoption signal","Install command has no obvious high-risk pattern","Outcome loop is ready but needs first real agent run"],"warnings":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access","No real agent outcome reports yet","Human review required before unattended installation"],"evidence":{"stars":"92K GitHub stars","repoActivity":"92K stars, 9.8K forks","lastPushed":"2d since push","license":"MIT","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","installSafety":"standard package or runtime install path","permissionSurface":"shell or command execution, filesystem or document access","documentation":"Strong README/SKILL.md context","agentOutcomes":"No agent outcome data yet","agentProvenScore":0,"outcomeConfidence":"0%","installPolicy":"human_review_before_install"},"installReadiness":{"ready":true,"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","policy":"human_review_before_install","label":"Human review before install","notes":["Install path is available","Repository evidence is available","License is declared","No Agent Proven outcome evidence yet","2d since push","Trust Score v5 requires review or sandbox-only use before install."]},"agentCompatibility":["Codex","Claude Code","Cursor","OpenAgentSkill CLI"],"riskSummary":{"level":"medium","label":"Review before production","notes":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"outcomeEvidence":{"total":0,"successes":0,"failures":0,"notRelevant":0,"successRate":null,"installAttempts":0,"riskBlocked":0,"setupRequired":0,"installSuccessRate":null,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"recentSuccessRate":null,"recentFailureRate":null,"uniqueAgents":0,"agentProvenScore":0,"agentProvenLabel":"Needs first agent run","lastOutcomeAt":null,"label":"No agent outcome data yet"},"autoInstall":{"allowed":false,"sandboxRequired":true,"policy":"human_review_before_install","reason":"Compare alternatives before installing."},"outcome_loop":{"version":"openagentskill-agent-outcome-v4","required_after_install":true,"endpoint":"/api/agent/outcome","method":"POST","event_id_source":"feedback.event_id, install_receipt.resolve_event_id, or decision_packet.outcome_feedback.event_id","expected_outcomes":["success","failed","not_relevant","blocked_by_risk","setup_required"],"required_fields":["event_id","skill_slug","task"],"quality_fields":["task_success","output_quality","error_type","human_review_required","used_in_production","workspace","evidence_url","time_to_useful_ms","source_version"],"ranking_inputs_updated":["Trust Score v5 outcome confidence","Agent Proven Score","Resolve ranking task-fit evidence","Skill detail machine-readable metadata","Outcome leaderboard"]},"agent_contract":{"suited_tasks":["research","agent-skill"],"suited_agents":["Codex","Claude Code","Cursor","OpenAgentSkill CLI"],"install_command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","trust_score":72,"trust_version":"trust-score-v5","risk_level":"medium","do_not_use_when":["Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"],"before_install":["Read the audit page and machine-readable metadata.","Confirm the install command, license, and permission surface fit the workspace.","Get explicit human approval or choose an alternative before installing."],"after_run":["Report the outcome to /api/agent/outcome using the resolve event id.","Include output_quality, workspace, human_review_required, and evidence_url when available.","Re-resolve before broad production rollout."]},"bestFor":["research","agent-skill"],"doNotUseFor":["Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"],"knownRisks":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"],"backward_compatible":{"trust_score_v4":{"version":"trust-score-v4","score":80,"tier":"strong","label":"Strong shortlist","summary":"Good trust signals with a few areas worth checking before rollout."}}},"trust_score_v4":{"version":"trust-score-v4","score":80,"tier":"strong","label":"Strong shortlist","summary":"Good trust signals with a few areas worth checking before rollout.","recommendedAction":"Test in a sandbox workflow and compare its install path with close alternatives.","dimensions":[{"id":"github_adoption","label":"GitHub adoption","score":100,"weight":0.13,"status":"pass","detail":"92K GitHub stars"},{"id":"repo_activity","label":"Stars/forks activity","score":100,"weight":0.08,"status":"pass","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"id":"maintenance","label":"Recent maintenance","score":100,"weight":0.14,"status":"pass","detail":"2d since push"},{"id":"license","label":"License clarity","score":86,"weight":0.09,"status":"pass","detail":"MIT"},{"id":"documentation","label":"README/SKILL.md completeness","score":86,"weight":0.14,"status":"pass","detail":"Metadata includes enough usage and workflow context"},{"id":"dependency_risk","label":"Dependency/runtime risk","score":74,"weight":0.12,"status":"info","detail":"network or browser surface, database surface"},{"id":"installability","label":"Install availability","score":92,"weight":0.1,"status":"pass","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"id":"install_safety","label":"Install command safety","score":92,"weight":0.1,"status":"pass","detail":"standard package or runtime install path"},{"id":"permission_surface","label":"Permission surface","score":36,"weight":0.07,"status":"fail","detail":"shell or command execution, filesystem or document access"},{"id":"repository","label":"Repository evidence","score":86,"weight":0.04,"status":"pass","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"id":"review_status","label":"Review status","score":66,"weight":0.05,"status":"info","detail":"AI review data available"},{"id":"agent_outcomes","label":"Agent Proven outcomes","score":54,"weight":0.13,"status":"info","detail":"No agent outcome data yet"}],"checks":[{"status":"pass","label":"GitHub adoption","detail":"92K GitHub stars"},{"status":"pass","label":"Stars/forks activity","detail":"92K stars, 9.8K forks; issue activity unavailable in current metadata"},{"status":"pass","label":"Recent maintenance","detail":"2d since push"},{"status":"pass","label":"License clarity","detail":"MIT"},{"status":"pass","label":"README/SKILL.md completeness","detail":"Metadata includes enough usage and workflow context"},{"status":"info","label":"Dependency/runtime risk","detail":"network or browser surface, database surface"},{"status":"pass","label":"Install availability","detail":"npx skills add addyosmani/agent-skills --skill spec-driven-development"},{"status":"pass","label":"Install command safety","detail":"standard package or runtime install path"},{"status":"fail","label":"Permission surface","detail":"shell or command execution, filesystem or document access"},{"status":"pass","label":"Repository evidence","detail":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development"},{"status":"info","label":"Review status","detail":"AI review data available"},{"status":"info","label":"Agent Proven outcomes","detail":"No agent outcome data yet"},{"status":"warn","label":"Ownership","detail":"No approved owner claim yet"},{"status":"pass","label":"OpenAgentSkill usage","detail":"2 views, 0 install copies"},{"status":"info","label":"Agent outcomes","detail":"No agent outcome data yet"}],"strengths":["AI review approved","Install path is available","Repository evidence is available","Recently maintained repository","Large GitHub adoption signal","Install command has no obvious high-risk pattern"],"warnings":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"],"evidence":{"stars":"92K GitHub stars","repoActivity":"92K stars, 9.8K forks","lastPushed":"2d since push","license":"MIT","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","installSafety":"standard package or runtime install path","permissionSurface":"shell or command execution, filesystem or document access","documentation":"Strong README/SKILL.md context","agentOutcomes":"No agent outcome data yet"},"installReadiness":{"ready":true,"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","policy":"human_review_before_install","label":"Human review before install","notes":["Install path is available","Repository evidence is available","License is declared","No Agent Proven outcome evidence yet","2d since push"]},"agentCompatibility":["Codex","Claude Code","Cursor","OpenAgentSkill CLI"],"riskSummary":{"level":"medium","label":"Review before production","notes":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"outcomeEvidence":{"total":0,"successes":0,"failures":0,"notRelevant":0,"successRate":null,"installAttempts":0,"riskBlocked":0,"setupRequired":0,"installSuccessRate":null,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"recentSuccessRate":null,"recentFailureRate":null,"uniqueAgents":0,"agentProvenScore":0,"agentProvenLabel":"Needs first agent run","lastOutcomeAt":null,"label":"No agent outcome data yet"},"autoInstall":{"allowed":false,"sandboxRequired":true,"policy":"human_review_before_install","reason":"Human review or sandbox validation is required before automatic installation."},"bestFor":["research","agent-skill"],"doNotUseFor":["Production credentials, payments, or irreversible account changes without explicit human review","Sensitive private data before reviewing repository code, license, and permission surface","Automatic installation in a production workspace"],"knownRisks":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"agent_proven":{"version":"agent-proven-v1","score":0,"tier":"unproven","label":"Needs first agent run","summary":"No agent outcome reports yet. Use Resolve, run one narrow sandbox task, then report the result.","metrics":{"totalOutcomes":0,"successfulOutcomes":0,"failedOutcomes":0,"installAttempts":0,"installSuccessRate":null,"successRate":null,"recentSuccessRate":null,"recentFailureRate":null,"riskBlocked":0,"setupRequired":0,"notRelevant":0,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"uniqueAgents":0,"lastOutcomeAt":null},"signals":[],"penalties":["No real agent outcome evidence yet"]},"outcome_stats":null,"safety":{"score":52,"level":"avoid_auto_install","label":"Avoid automatic install","safety_tier":{"tier":"experimental","label":"Experimental","badge":"EXPERIMENTAL","summary":"Sparse or mixed signals. Useful for discovery, but not for autonomous installation.","recommended_action":"Test manually in an isolated workspace and compare against safer alternatives.","auto_install_policy":"review","reasons":["High-risk permission hints: Shell or command execution","52/100 agent safety score"]},"auto_install_allowed":false,"human_review_required":true,"blocked":false,"audit_risk":"needs_review","permission_hints":[{"id":"shell","label":"Shell or command execution","reason":"Skill metadata references terminal, CLI, shell, subprocess, or command execution workflows.","severity":"high"},{"id":"browser","label":"Browser automation","reason":"Skill may drive a browser or interact with web pages.","severity":"medium"},{"id":"network","label":"Network access","reason":"Skill likely fetches remote pages, APIs, repositories, or external services.","severity":"medium"},{"id":"filesystem","label":"Filesystem access","reason":"Skill may read or write project files, documents, generated artifacts, or local workspace state.","severity":"medium"},{"id":"database","label":"Database access","reason":"Skill may inspect schemas, query databases, or work with persistent stores.","severity":"medium"}],"policy_warnings":["High-risk permission hints: Shell or command execution","Permission surface may require sandboxing"],"constraints_applied":{"max_risk":"medium","needs_install_command":true,"min_stars":0}},"safety_gate":{"tier":"experimental","label":"Experimental","badge":"EXPERIMENTAL","auto_install_policy":"review","auto_install_allowed":false,"blocked":false,"human_review_required":true,"recommended_action":"Test manually in an isolated workspace and compare against safer alternatives.","reasons":["High-risk permission hints: Shell or command execution","52/100 agent safety score"]},"eval":{"version":"openagentskill-skill-eval-v1","status":"failed","score":81,"risk_level":"high","decision":{"recommendation":"do_not_auto_install","reason":"Permission surface: shell or command execution, filesystem or document access","auto_install_allowed":false,"policy":"block","human_review_required":true},"blockers":["Permission surface: shell or command execution, filesystem or document access"],"warnings":["Trust score: Good trust signals with a few areas worth checking before rollout.","Audit score: Needs review","Agent safety gate: Sparse or mixed signals. Useful for discovery, but not for autonomous installation.","High-risk permission hints: Shell or command execution","Permission surface may require sandboxing","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"],"validation_plan":["Inspect repository, README/SKILL.md, license, and recent commits before production use.","Install in an isolated workspace or sandbox with no production secrets available.","Run the smallest representative task and record files touched, commands run, network access, and outputs.","Compare the selected skill against at least one alternative when the eval status is review or failed.","Promote only after the agent reports a successful verification result and unresolved warnings are accepted."],"checks":[{"id":"task_fit","label":"Task fit","status":"pass","score":94,"required_for_auto_install":true,"detail":"Task wording matches this skill metadata.","evidence":["Evaluate spec-driven-development before installing it in an agent workflow","research","Coding agents workflows; Claude Code teams; teams that value GitHub adoption signals"]},{"id":"install_path","label":"Install path","status":"pass","score":92,"required_for_auto_install":true,"detail":"Install handoff is available.","evidence":["npx skills add addyosmani/agent-skills --skill spec-driven-development"]},{"id":"install_safety","label":"Install command safety","status":"pass","score":92,"required_for_auto_install":true,"detail":"standard package or runtime install path","evidence":["npx skills add addyosmani/agent-skills --skill spec-driven-development"]},{"id":"trust_score","label":"Trust score","status":"warn","score":80,"required_for_auto_install":true,"detail":"Good trust signals with a few areas worth checking before rollout.","evidence":["Strong shortlist","92K GitHub stars","MIT"]},{"id":"audit_score","label":"Audit score","status":"warn","score":88,"required_for_auto_install":true,"detail":"Needs review","evidence":["Permission surface may require sandboxing"]},{"id":"agent_safety_gate","label":"Agent safety gate","status":"warn","score":52,"required_for_auto_install":true,"detail":"Sparse or mixed signals. Useful for discovery, but not for autonomous installation.","evidence":["Test manually in an isolated workspace and compare against safer alternatives.","High-risk permission hints: Shell or command execution"]},{"id":"readme_skillmd_completeness","label":"README/SKILL.md completeness","status":"pass","score":86,"required_for_auto_install":false,"detail":"Metadata includes enough usage and workflow context","evidence":["Strong README/SKILL.md context"]},{"id":"license_clarity","label":"License clarity","status":"pass","score":86,"required_for_auto_install":true,"detail":"MIT","evidence":["MIT"]},{"id":"recent_maintenance","label":"Recent maintenance","status":"pass","score":100,"required_for_auto_install":false,"detail":"2d since push","evidence":["2d since push"]},{"id":"permission_surface","label":"Permission surface","status":"fail","score":36,"required_for_auto_install":true,"detail":"shell or command execution, filesystem or document access","evidence":["Shell or command execution: high","Browser automation: medium","Network access: medium"]},{"id":"alternatives","label":"Alternatives available","status":"info","score":55,"required_for_auto_install":false,"detail":"No close alternatives were found in the current shortlist.","evidence":[]}],"endpoints":{"web":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development/evals","api":"/api/agent/evals?slug=addyosmani-spec-driven-development","text":"/api/agent/evals?slug=addyosmani-spec-driven-development&format=text"}},"agent_readable_metadata":{"version":"openagentskill-agent-metadata-v2","skill":{"slug":"addyosmani-spec-driven-development","name":"spec-driven-development","description":"Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.","category":"research","url":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","github_repo":"addyosmani/agent-skills"},"suited_tasks":["Coding agents workflows","Claude Code teams","teams that value GitHub adoption signals","Inspect source files","Explain architecture","Patch bugs and verify changes","Run test suites","Capture failures"],"suited_agents":["Codex","Claude Code","Cursor","OpenAgentSkill CLI","Browser agents","CLI"],"install":{"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","ready":true,"targets":[{"id":"openagentskill-cli","label":"CLI","kind":"command","value":"npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add addyosmani-spec-driven-development"},{"id":"codex","label":"Codex","kind":"agent-prompt","value":"Install the \"spec-driven-development\" agent skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"codex\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."},{"id":"claude-code","label":"Claude Code","kind":"agent-prompt","value":"Add \"spec-driven-development\" as a Claude Code skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Inspect the skill instructions, place the reusable skill files in the appropriate local skills location for this project, and report the activation steps. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"claude-code\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."},{"id":"cursor","label":"Cursor","kind":"agent-prompt","value":"Turn \"spec-driven-development\" from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development into a reusable Cursor project rule or agent instruction. Preserve the core workflow, adapt paths to this repo, and keep the rule scoped to tasks where it is relevant. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"cursor\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."}],"handoff_url":"https://www.openagentskill.com/api/skills/addyosmani-spec-driven-development/install","manifest_url":"https://www.openagentskill.com/api/registry/manifest/addyosmani-spec-driven-development"},"trust":{"score":80,"label":"Strong shortlist","version":"trust-score-v4","install_policy":"human_review_before_install","evidence":{"stars":"92K GitHub stars","repoActivity":"92K stars, 9.8K forks","lastPushed":"2d since push","license":"MIT","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","installSafety":"standard package or runtime install path","permissionSurface":"shell or command execution, filesystem or document access","documentation":"Strong README/SKILL.md context","agentOutcomes":"No agent outcome data yet"},"outcome_evidence":{"total":0,"successes":0,"failures":0,"not_relevant":0,"success_rate":null,"recent_success_rate":null,"recent_failure_rate":null,"install_attempts":0,"install_success_rate":null,"risk_blocked":0,"setup_required":0,"avg_output_quality":null,"production_outcomes":0,"last_outcome_at":null,"label":"No agent outcome data yet"},"auto_install":{"allowed":false,"sandbox_required":true,"reason":"Human review or sandbox validation is required before automatic installation."},"best_for":["research","agent-skill"],"known_risks":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"agent_proven":{"version":"agent-proven-v1","score":0,"tier":"unproven","label":"Needs first agent run","summary":"No agent outcome reports yet. Use Resolve, run one narrow sandbox task, then report the result.","metrics":{"totalOutcomes":0,"successfulOutcomes":0,"failedOutcomes":0,"installAttempts":0,"installSuccessRate":null,"successRate":null,"recentSuccessRate":null,"recentFailureRate":null,"riskBlocked":0,"setupRequired":0,"notRelevant":0,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"uniqueAgents":0,"lastOutcomeAt":null},"signals":[],"penalties":["No real agent outcome evidence yet"]},"audit":{"score":88,"risk_level":"needs_review","risk_label":"Needs review","warnings":["Permission surface may require sandboxing","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"safety_gate":{"tier":"experimental","label":"Experimental","auto_install_policy":"review","auto_install_allowed":false,"human_review_required":true,"blocked":false,"recommended_action":"Test manually in an isolated workspace and compare against safer alternatives."},"quality":{"score":95,"label":"Excellent"},"supply":{"track":"Coding and developer agents","scenario":"Coding agents","maintenance":"2d since push","risk":"Needs review"},"alternative_skills":[],"do_not_use_when":["teams that need a vendor-supported SLA","production agents without a repository review","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","High-risk permission hints: Shell or command execution","Permission surface may require sandboxing","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access","Production credentials, payments, or irreversible account changes without explicit human review"],"agent_contract":{"task_input":"Use spec-driven-development in an agent workflow","recommended_action":"Test manually in an isolated workspace and compare against safer alternatives.","install_policy":"review","minimum_review_before_use":["Trust: 80/100 Strong shortlist","Audit: 88/100 Needs review","Safety: 52/100 Avoid automatic install","Review repository, license, install command, and permission surface before production use."],"expected_agent_output":{"selected_skill":"addyosmani-spec-driven-development (spec-driven-development)","install_command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","risk_summary":"Needs review; Experimental; Review before production","verification_result":"Report the smallest successful task, files touched, warnings, and any missing setup."}},"outcome_feedback":{"endpoint":"https://www.openagentskill.com/api/agent/outcome","method":"POST","requires_resolve_event_id":true,"event_id_source":"Use install_receipt.outcome_feedback.event_id or feedback.event_id returned by /api/agent/resolve for the current task.","expected_outcomes":["success","failed","not_relevant","blocked_by_risk","setup_required"],"payload_template":{"event_id":"<install_receipt.outcome_feedback.event_id or feedback.event_id from /api/agent/resolve>","skill_slug":"addyosmani-spec-driven-development","task":"Use spec-driven-development in an agent workflow","agent":"codex","outcome":"success","install_used":true,"risk_blocked":false,"setup_required":false,"task_success":true,"output_quality":4,"error_type":null,"human_review_required":false,"workspace":"sandbox","time_to_useful_ms":120000,"notes":"Report the smallest successful task, setup friction, files touched, and risk notes."}},"endpoints":{"web":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development","api":"https://www.openagentskill.com/api/agent/skills/addyosmani-spec-driven-development","audit":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development/audit","eval":"https://www.openagentskill.com/api/agent/evals?slug=addyosmani-spec-driven-development&task=Use%20spec-driven-development%20in%20an%20agent%20workflow&max_risk=medium","resolve":"https://www.openagentskill.com/api/agent/resolve?task=Use%20spec-driven-development%20in%20an%20agent%20workflow&agent=codex&max_risk=medium","receipt":"https://www.openagentskill.com/api/agent/receipt?task=Use%20spec-driven-development%20in%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text","install":"https://www.openagentskill.com/api/skills/addyosmani-spec-driven-development/install","manifest":"https://www.openagentskill.com/api/registry/manifest/addyosmani-spec-driven-development"}},"machine_metadata":{"version":"openagentskill-agent-metadata-v2","skill":{"slug":"addyosmani-spec-driven-development","name":"spec-driven-development","description":"Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.","category":"research","url":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","github_repo":"addyosmani/agent-skills"},"suited_tasks":["Coding agents workflows","Claude Code teams","teams that value GitHub adoption signals","Inspect source files","Explain architecture","Patch bugs and verify changes","Run test suites","Capture failures"],"suited_agents":["Codex","Claude Code","Cursor","OpenAgentSkill CLI","Browser agents","CLI"],"install":{"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","ready":true,"targets":[{"id":"openagentskill-cli","label":"CLI","kind":"command","value":"npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add addyosmani-spec-driven-development"},{"id":"codex","label":"Codex","kind":"agent-prompt","value":"Install the \"spec-driven-development\" agent skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"codex\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."},{"id":"claude-code","label":"Claude Code","kind":"agent-prompt","value":"Add \"spec-driven-development\" as a Claude Code skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Inspect the skill instructions, place the reusable skill files in the appropriate local skills location for this project, and report the activation steps. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"claude-code\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."},{"id":"cursor","label":"Cursor","kind":"agent-prompt","value":"Turn \"spec-driven-development\" from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development into a reusable Cursor project rule or agent instruction. Preserve the core workflow, adapt paths to this repo, and keep the rule scoped to tasks where it is relevant. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"cursor\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes."}],"handoff_url":"https://www.openagentskill.com/api/skills/addyosmani-spec-driven-development/install","manifest_url":"https://www.openagentskill.com/api/registry/manifest/addyosmani-spec-driven-development"},"trust":{"score":80,"label":"Strong shortlist","version":"trust-score-v4","install_policy":"human_review_before_install","evidence":{"stars":"92K GitHub stars","repoActivity":"92K stars, 9.8K forks","lastPushed":"2d since push","license":"MIT","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","installSafety":"standard package or runtime install path","permissionSurface":"shell or command execution, filesystem or document access","documentation":"Strong README/SKILL.md context","agentOutcomes":"No agent outcome data yet"},"outcome_evidence":{"total":0,"successes":0,"failures":0,"not_relevant":0,"success_rate":null,"recent_success_rate":null,"recent_failure_rate":null,"install_attempts":0,"install_success_rate":null,"risk_blocked":0,"setup_required":0,"avg_output_quality":null,"production_outcomes":0,"last_outcome_at":null,"label":"No agent outcome data yet"},"auto_install":{"allowed":false,"sandbox_required":true,"reason":"Human review or sandbox validation is required before automatic installation."},"best_for":["research","agent-skill"],"known_risks":["No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"agent_proven":{"version":"agent-proven-v1","score":0,"tier":"unproven","label":"Needs first agent run","summary":"No agent outcome reports yet. Use Resolve, run one narrow sandbox task, then report the result.","metrics":{"totalOutcomes":0,"successfulOutcomes":0,"failedOutcomes":0,"installAttempts":0,"installSuccessRate":null,"successRate":null,"recentSuccessRate":null,"recentFailureRate":null,"riskBlocked":0,"setupRequired":0,"notRelevant":0,"avgOutputQuality":null,"avgTimeToUsefulMs":null,"productionOutcomes":0,"humanReviewRequired":0,"uniqueAgents":0,"lastOutcomeAt":null},"signals":[],"penalties":["No real agent outcome evidence yet"]},"audit":{"score":88,"risk_level":"needs_review","risk_label":"Needs review","warnings":["Permission surface may require sandboxing","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"safety_gate":{"tier":"experimental","label":"Experimental","auto_install_policy":"review","auto_install_allowed":false,"human_review_required":true,"blocked":false,"recommended_action":"Test manually in an isolated workspace and compare against safer alternatives."},"quality":{"score":95,"label":"Excellent"},"supply":{"track":"Coding and developer agents","scenario":"Coding agents","maintenance":"2d since push","risk":"Needs review"},"alternative_skills":[],"do_not_use_when":["teams that need a vendor-supported SLA","production agents without a repository review","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","High-risk permission hints: Shell or command execution","Permission surface may require sandboxing","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access","Production credentials, payments, or irreversible account changes without explicit human review"],"agent_contract":{"task_input":"Use spec-driven-development in an agent workflow","recommended_action":"Test manually in an isolated workspace and compare against safer alternatives.","install_policy":"review","minimum_review_before_use":["Trust: 80/100 Strong shortlist","Audit: 88/100 Needs review","Safety: 52/100 Avoid automatic install","Review repository, license, install command, and permission surface before production use."],"expected_agent_output":{"selected_skill":"addyosmani-spec-driven-development (spec-driven-development)","install_command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","risk_summary":"Needs review; Experimental; Review before production","verification_result":"Report the smallest successful task, files touched, warnings, and any missing setup."}},"outcome_feedback":{"endpoint":"https://www.openagentskill.com/api/agent/outcome","method":"POST","requires_resolve_event_id":true,"event_id_source":"Use install_receipt.outcome_feedback.event_id or feedback.event_id returned by /api/agent/resolve for the current task.","expected_outcomes":["success","failed","not_relevant","blocked_by_risk","setup_required"],"payload_template":{"event_id":"<install_receipt.outcome_feedback.event_id or feedback.event_id from /api/agent/resolve>","skill_slug":"addyosmani-spec-driven-development","task":"Use spec-driven-development in an agent workflow","agent":"codex","outcome":"success","install_used":true,"risk_blocked":false,"setup_required":false,"task_success":true,"output_quality":4,"error_type":null,"human_review_required":false,"workspace":"sandbox","time_to_useful_ms":120000,"notes":"Report the smallest successful task, setup friction, files touched, and risk notes."}},"endpoints":{"web":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development","api":"https://www.openagentskill.com/api/agent/skills/addyosmani-spec-driven-development","audit":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development/audit","eval":"https://www.openagentskill.com/api/agent/evals?slug=addyosmani-spec-driven-development&task=Use%20spec-driven-development%20in%20an%20agent%20workflow&max_risk=medium","resolve":"https://www.openagentskill.com/api/agent/resolve?task=Use%20spec-driven-development%20in%20an%20agent%20workflow&agent=codex&max_risk=medium","receipt":"https://www.openagentskill.com/api/agent/receipt?task=Use%20spec-driven-development%20in%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text","install":"https://www.openagentskill.com/api/skills/addyosmani-spec-driven-development/install","manifest":"https://www.openagentskill.com/api/registry/manifest/addyosmani-spec-driven-development"}},"supply_profile":{"track":{"slug":"coding","label":"Coding and developer agents","shortLabel":"Coding","description":"Code review, repo analysis, testing, CI, GitHub, DevOps, and developer workflow skills."},"scenario":{"label":"Coding agents","description":"I need a coding agent that can understand a repository, edit code, and review pull requests.","useCases":[{"slug":"coding-agents","title":"Coding agents"},{"slug":"testing-qa","title":"Testing and QA"},{"slug":"browser-automation","title":"Browser automation"}]},"applicableAgents":["Claude Code","Browser agents","CLI","Codex","Cursor"],"install":{"ready":true,"command":"npx skills add addyosmani/agent-skills --skill spec-driven-development","primaryTarget":"CLI","targetCount":4},"githubQuality":{"stars":92201,"starsLabel":"92K","forks":9827,"license":"MIT","qualityScore":95,"trustScore":80,"auditScore":88},"maintenance":{"status":"fresh","label":"2d since push","daysSincePush":2,"lastPushedAt":"2026-09-04T06:45:55+00:00"},"risk":{"level":"needs_review","label":"Needs review","requiresReview":true,"notes":["Permission surface may require sandboxing","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access","Needs review"]},"coverageTags":["Coding","Coding agents","research","agent-skill"]},"audit":{"audit_score":88,"risk_level":"needs_review","risk_label":"Needs review","quality_score":95,"trust_score":80,"maintenance_score":100,"security_score":77,"install_score":92,"warnings":["Permission surface may require sandboxing","No security issues found. The skill is a planning/specification workflow with human review gates and does not instruct unsafe command execution, secret access, or hidden actions.","Permission surface needs review: shell or command execution, filesystem or document access","Permission surface: shell or command execution, filesystem or document access"]},"quality_signals":{"model":"v2","star_score":34.75,"usage_score":0,"review_score":5.55,"metadata_score":3,"freshness_score":15},"platforms":["Claude Code","Browser agents"],"use_cases":[{"slug":"coding-agents","title":"Coding agents","url":"https://www.openagentskill.com/use-cases/coding-agents"},{"slug":"testing-qa","title":"Testing and QA","url":"https://www.openagentskill.com/use-cases/testing-qa"},{"slug":"browser-automation","title":"Browser automation","url":"https://www.openagentskill.com/use-cases/browser-automation"},{"slug":"research-agents","title":"Research agents","url":"https://www.openagentskill.com/use-cases/research-agents"}],"stacks":[{"slug":"coding-review-agent","title":"Coding review agent","url":"https://www.openagentskill.com/collections/coding-review-agent"},{"slug":"browser-qa-agent","title":"Browser QA agent","url":"https://www.openagentskill.com/collections/browser-qa-agent"},{"slug":"research-report-agent","title":"Research report agent","url":"https://www.openagentskill.com/collections/research-report-agent"}],"install":"npx skills add addyosmani/agent-skills --skill spec-driven-development","install_targets":[{"id":"openagentskill-cli","label":"CLI","title":"OpenAgentSkill CLI","kind":"command","value":"npx --yes https://github.com/Leon-Drq/openagentskill/releases/download/cli-v0.3.0/openagentskill-0.3.0.tgz add addyosmani-spec-driven-development","description":"Resolve policy, run the source installer safely, and report a verified install receipt.","copyLabel":"Copy command"},{"id":"codex","label":"Codex","title":"Codex install prompt","kind":"agent-prompt","value":"Install the \"spec-driven-development\" agent skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"codex\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.","description":"Give Codex a repo-aware install prompt when the skill is not available through a local CLI.","copyLabel":"Copy prompt"},{"id":"claude-code","label":"Claude Code","title":"Claude Code skill prompt","kind":"agent-prompt","value":"Add \"spec-driven-development\" as a Claude Code skill from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development. Inspect the skill instructions, place the reusable skill files in the appropriate local skills location for this project, and report the activation steps. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"claude-code\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.","description":"Use this prompt to ask Claude Code to add the skill and explain the local activation steps.","copyLabel":"Copy prompt"},{"id":"cursor","label":"Cursor","title":"Cursor rule prompt","kind":"agent-prompt","value":"Turn \"spec-driven-development\" from https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development into a reusable Cursor project rule or agent instruction. Preserve the core workflow, adapt paths to this repo, and keep the rule scoped to tasks where it is relevant. Skill purpose: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {\"event_id\":\"install_<unique-id>\",\"skill_slug\":\"addyosmani-spec-driven-development\",\"task\":\"Install spec-driven-development\",\"agent\":\"cursor\",\"outcome\":\"success\",\"install_used\":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.","description":"Use this when installing as Cursor project rules or reusable agent instructions.","copyLabel":"Copy prompt"}],"repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","github_repo":"addyosmani/agent-skills","version":"1.0.0","license":"MIT","urls":{"web":"https://www.openagentskill.com/skills/addyosmani-spec-driven-development","repository":"https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development","api":"/api/agent/skills/addyosmani-spec-driven-development","install_api":"/api/skills/addyosmani-spec-driven-development/install"},"meta":{"created_at":"2026-09-04T13:22:31.431347+00:00","updated_at":"2026-09-04T13:22:31.569795+00:00","agent_friendly":true}}