New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Feature Specification

by owainlewis in owainlewis/blueprint

Writes one implementation-ready spec for a feature or major change, settling behavior, technical design, failure handling and acceptance checks before delivery.

MITAuto-check passedDevelopment

Install Feature Specification

skills CLI
$ npx skills add owainlewis/blueprint --skill spec -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install owainlewis/blueprint spec --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/owainlewis/blueprint.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/spec .claude/skills/spec && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
spec
GitHub stars
412
Token cost
~938 tokens
SKILL.md length
474 words
Files
1
Skills in repo
11
Repo updated
First seen
Licence
MIT

At a glance

Writes one implementation-ready spec for a feature or major change, settling behavior, technical design, failure handling and acceptance checks before delivery.

  • Works in 5 steps: Read the request, repository… → Define the outcome and scope. Ask about… → Write the spec using the shape below.… → …
  • Defining a feature before delivery when design choices have consequences
  • SKILL.md covers Process, Spec shape, Lifecycle and Boundaries, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The agent reads the request, repository instructions, requirements, architecture and relevant code, then asks about unresolved choices that could change behavior, data, interfaces, security, compatibility, operations, cost or proof, leaving reversible local details to implementation. The spec is the ticket, so it updates a supplied source such as a GitHub issue or a Markdown file under docs, and publishes to a tracker only when asked.

The spec has four parts: outcome and scope, required behavior, technical design, and acceptance and proof, where each acceptance row pairs a done-when condition with a way to check it. The agent then checks that a fresh agent could build from it without inventing a consequential decision, traces success, denial, invalid input and partial failure, and stops with the spec ready for review without planning tasks or implementing.

When your agent uses it

  • Defining a feature before delivery when design choices have consequences
  • Turning a GitHub issue into an implementation-ready specification
  • Checking that failure handling and acceptance checks are settled
  • Proposing an architecture change for review before any coding

Example prompts

  • “Write a spec for adding team invitations to the workspace settings page.”
  • “Update the spec in docs/export/spec.md to cover partial failure on large exports.”
  • “Spec out moving session storage to Redis, including rollout and rollback.”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Read the request, repository instructions, requirements, architecture, and relevant implementation. Reuse settled decisions and verify…
  2. Define the outcome and scope. Ask about unresolved choices that could change behavior, data, interfaces, security, compatibility…
  3. Write the spec using the shape below. Explain the change from current behavior; link shared requirements and architecture instead of…
  4. Check that a fresh agent could implement it without inventing a consequential decision. Trace success, denial, invalid input, and partial…
  5. Stop with the spec ready for review. Do not plan tasks or implement it.

What it can do on your machine

Read from SKILL.md and the folder at commit 1d74745. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Feature Specification loads about 938 tokens when it runs. Until then it costs about 52 tokens; SKILL.md has 474 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~52
When it runs · the whole SKILL.md, loaded when a task matches
~938

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from owainlewis/blueprint at commit 1d74745, republished under its MIT licence (© owainlewis). 474 words, ~938 tokens.

Download SKILL.mdSave it as .claude/skills/spec/SKILL.md (or your agent's skills folder).
name
spec
description
Defines one feature or major change: required behavior, technical design, failure handling, and acceptance checks. Use when consequential decisions must be settled before delivery. The spec is the ticket.
user-invocable
true
argument-hint
<feature, change, issue, or brief>

Spec

Write one implementation-ready specification for one coherent change. The spec is the ticket: its source may be docs/<feature-slug>/spec.md, a GitHub issue, or another user-supplied document. Update the supplied source; do not create a duplicate ticket or document. Without a supplied source, use the Markdown path above. Publish to a tracker only when asked.

Process

  1. Read the request, repository instructions, requirements, architecture, and relevant implementation. Reuse settled decisions and verify claims about current behavior.
  2. Define the outcome and scope. Ask about unresolved choices that could change behavior, data, interfaces, security, compatibility, operations, cost, or proof. Leave reversible local mechanics to implementation.
  3. Write the spec using the shape below. Explain the change from current behavior; link shared requirements and architecture instead of restating them.
  4. Check that a fresh agent could implement it without inventing a consequential decision. Trace success, denial, invalid input, and partial failure where relevant.
  5. Stop with the spec ready for review. Do not plan tasks or implement it.

Spec shape

Outcome and scope

State the problem, affected user or caller, desired result, constraints, and non-goals.

Required behavior

Describe inputs, actions, observable results, permissions, business rules, and failure recovery. Reference applicable REQ-n IDs. Settle feature-specific product details here.

Technical design

Explain changed responsibilities, interfaces, data, and execution order. Use concrete types, payloads, state tables, or diagrams when they remove ambiguity.

Cover schema changes, indexes, migrations, transaction boundaries, concurrency, retries, cancellation, security, compatibility, observability, rollout, and rollback only where they affect the change. State important choices, their reasons, and their costs.

Name any required change to system architecture. Do not silently override an accepted rule. Record the proposed architecture change for review before delivery.

Show full SKILL.md (195 more words)Show less
Acceptance and proof

Pair each observable condition and affected architectural rule with a check.

IDDone whenHow to check
AC-1Concrete resultCommand, automated scenario, or manual check

Preserve existing AC-n, REQ-n, and INV-n references. Never reuse or renumber IDs. Do not invent executable commands for code that does not exist; define the scenario and expected result instead.

Open decisions

State missing answers, recommended defaults when justified, and whether they block delivery. Write None when settled. Do not hide unknowns behind placeholders.

Lifecycle

State the decision status and delivery status separately. After delivery, retain the spec as a record of the feature decisions and acceptance checks. Link delivered PRs and proof without claiming unrun checks passed. Record consequential changes made during delivery; do not erase the reasoning. Keep current product and system rules in requirements and architecture.

Boundaries

One spec may lead to several tasks and pull requests. Use /plan when splitting helps delivery. Small, decided fixes can use their task description and checks without a formal spec. Do not require root documents for a local change that does not need them.

Return

Report the source, main decision and tradeoff, and any blocking question.

© owainlewis, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/spec of owainlewis/blueprint.

Open the folder on GitHubat commit 1d74745

Compare with similar skills

Feature Specification next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Feature Specification compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Feature Specification this skillowainlewis/blueprint412—~938Automated safety check: PassMIT
MVP Technical DesignKhazP/vibe-coding-prompt-template3.1k—~512Automated safety check: PassMIT
Spec Writergarrytan/gstack136k—~14kAutomated safety check: NotesMIT
Dark Architecture Diagram BuilderCocoon-AI/architecture-diagram-generator7.4k1 repos~2.1kAutomated safety check: PassMIT
Update .NET OS Packagesdotnet/core22k—~2.3kAutomated safety check: PassMIT
Beautify GitHub Readmeoil-oil/beautify-github-readme1.8k—~4.1kAutomated safety check: PassMIT

Similar skills

  • MVP Technical Design

    KhazP/vibe-coding-prompt-template

    Writes an MVP technical design from agreed requirements, covering architecture, data ownership, integration contracts, deployment and tradeoffs, then hands off to the next stage.

    3.1k GitHub stars~512 tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • Spec Writer

    garrytan/gstack

    Converts a vague idea into a precise, executable spec in five phases, files it as an issue and can start an agent on it in a fresh worktree.

    136k GitHub stars~14k tokensUpdated today
    DevelopmentAuto-check: notes

  • Dark Architecture Diagram Builder

    Cocoon-AI/architecture-diagram-generator

    Creates dark-themed system, cloud, security and network architecture diagrams as self-contained HTML files with inline SVG and CSS.

    7.4k GitHub starsUsed in 1 repo~2.1k tokens
    DevelopmentAuto-check passed

  • Update .NET OS Packages

    dotnet/core

    Official

    Audits and updates os-packages.json files listing the Linux packages each .NET release needs per distro, then regenerates the Markdown from the JSON.

    22k GitHub stars~2.3k tokensUpdated today
    DevelopmentAuto-check passed

  • Beautify GitHub Readme

    oil-oil/beautify-github-readme

    Redesign GitHub README homepages or create project-native pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets.

    1.8k GitHub stars~4.1k tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • Library Documentation Seeker

    withkynam/vibecode-pro-max-kit

    Looks up library and framework documentation through Context7 first, with bundled Node scripts as a fallback that fetch and analyze llms.txt files.

    1.1k GitHub starsUsed in 2 repos~1k tokens
    DevelopmentAuto-check: notes

More from owainlewis/blueprint

All 11 skills in this repo

  • Markdown PRD to HTML Renderer

    owainlewis/blueprint

    Converts a complete Markdown PRD or technical design into one verified, static HTML reading page without changing what it says.

    412 GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed

  • Codex Issue Coordinator

    owainlewis/blueprint

    Lets one Codex thread run a batch of GitHub issues through separate worker threads, each with its own worktree, branch, tested pull request and gated merge.

    412 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check passed

  • Vertical-Slice Task Planner

    owainlewis/blueprint

    Breaks a reviewed spec into ordered, vertical-slice tasks that each fit one agent run and one pull request, grouped into milestones when useful.

    412 GitHub stars~1.5k tokensUpdated yesterday
    Auto-check passed

  • Independent Implementation Review

    owainlewis/blueprint

    Has a separate agent review a code change without editing it, checking behavior, security, regressions, complexity, tests and docs before merge.

    412 GitHub stars~1.5k tokensUpdated yesterday
    Auto-check passed

  • Architecture

    owainlewis/blueprint

    Designs and maintains root ARCHITECTURE.md for the intended system, including its data model and shared technical rules.

    412 GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed

  • Architecture Review

    owainlewis/blueprint

    Reviews a technical proposal before implementation through an independent subagent, returning findings, open questions and a verdict without rewriting it.

    412 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Feature Specification

What does Feature Specification do?

Writes one implementation-ready spec for a feature or major change, settling behavior, technical design, failure handling and acceptance checks before delivery. The agent reads the request, repository instructions, requirements, architecture and relevant code, then asks about unresolved choices that could change behavior, data, interfaces, security, compatibility, operations, cost or proof, leaving reversible local details to implementation. The spec is the ticket, so it updates a supplied source such as a GitHub issue or a Markdown file under docs, and publishes to a tracker only when asked.

When should I use Feature Specification?

Feature Specification fits situations like: defining a feature before delivery when design choices have consequences; turning a GitHub issue into an implementation-ready specification; checking that failure handling and acceptance checks are settled; proposing an architecture change for review before any coding.

How do I install Feature Specification in Claude Code?

Run `npx skills add owainlewis/blueprint --skill spec -a claude-code`. Or copy the skill folder (skills/spec in owainlewis/blueprint) into .claude/skills/spec in your project. Claude Code loads it when a task matches its description.

How do I install Feature Specification in Codex?

Run `npx skills add owainlewis/blueprint --skill spec -a codex`. Or copy the skill folder (skills/spec in owainlewis/blueprint) into .agents/skills/spec in your project. Codex loads it when a task matches its description.

Can I use Feature Specification in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add owainlewis/blueprint --skill spec -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/spec, .gemini/skills/spec, .github/skills/spec and .opencode/skills/spec in your project.

What does Feature Specification need to run?

SKILL.md names no scripts, command-line tools or credentials: Feature Specification is instructions for the agent only.

Does Feature Specification access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Feature Specification safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Feature Specification use?

Feature Specification is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Feature Specification use?

About 938 tokens (SKILL.md is roughly 3.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Feature Specification?

Skills that share tags, products or a category with Feature Specification: MVP Technical Design (KhazP/vibe-coding-prompt-template, 3.1k stars), Spec Writer (garrytan/gstack, 136k stars), Dark Architecture Diagram Builder (Cocoon-AI/architecture-diagram-generator, 7.4k stars) and Update .NET OS Packages (dotnet/core, 22k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Feature Specification?

owainlewis (a GitHub user) maintains it in owainlewis/blueprint, which has 412 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 6, 2026.

Source: owainlewis/blueprint on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.