Create spec

Turn a clear idea into a plan your agent can implement.

View skill & templates

Use Avthar's Skills and templates in your next project

Use the /brainstorm and /create-spec skill to plan your next AI coding project

Choose your agent

Claude Code

Codex

Grok Bot

Then paste it into a conversation with your agent.

Install both skills for your personal Claude Code projects.

The prompt installs and confirms. It won’t start a planning session.

Read the installation prompt

Install the brainstorm and create-spec skills from this manifest for use in the agent I am using now:
https://ainativebuilder.com/plan/resources/manifest.json

Identify this agent and use its supported personal/global skill installation or saved-skill mechanism, so the skills are reusable beyond the current project or conversation. If the correct mechanism is unclear, check this agent's official instructions before proceeding.

Fetch the manifest and download every listed file from the same origin. Preserve the exact contents and relative references, including both SKILL.md files and all four referenced Markdown files. Stage the complete bundle and verify its SHA-256 hashes before installation. If a download or hash check fails, stop and report it without changing existing skills. Back up any existing same-name skills before replacing them; keep filesystem backups outside skill-discovery directories. Install independent copies, not symlinks.

Verify that both skills are saved and discoverable and that every referenced template is accessible. If this host cannot preserve the complete bundle, explain the limitation instead of claiming successful installation. Report any enablement or refresh step still needed.

Confirm what was installed and where, then stop. Do not invoke either skill, start an interview, plan a project, or implement anything.

When to use it

Your brainstorm is clear enough to turn into concrete requirements.
A new product needs a shared plan for its architecture and constraints.
A change to an existing product needs focused scope and acceptance criteria.

How it works

Read the context
Your agent reads your idea, brainstorm, or issue alongside the relevant code and project documentation. The plan starts from what already exists.
Resolve important gaps
It asks targeted questions only when the available context leaves a decision that matters to scope or implementation. Facts, assumptions, and open decisions are labelled.
Save the spec
It chooses the appropriate template and saves a concise local document. Each success criterion gets a verification method and an explicit passing result, including important failure cases.

What you get

A saved project or feature spec with requirements, important decisions, and a Success and Verification section. A project spec covers a new product or large initiative; a feature spec covers a change to something that exists.

You’re ready to move on when…

Requirements make the included work and scope boundaries concrete.
Observed facts, assumptions, and unresolved decisions are distinguishable.
Success criteria say how to verify the result and what counts as passing.

Full instructions & templates

Read each complete file below. Copy or download the original Markdown to use with your agent.

Create spec skill

SKILL.md

Select and copy the complete source below.

---
name: create-spec
description: Create an actionable product and engineering spec from an idea, planning document, or GitHub or Linear issue. Use when the user asks for a spec or PRD.
---

# Create Spec

Produce a working spec grounded in the user's goal and what already exists in the repository. A **project spec** covers a new product or large initiative; a **feature spec** covers a change to something that exists. Pick by the size of the work, not by whether the input was a file or an issue.

## Gather context

- Input is the current request plus any invocation text: an inline idea, a local file to read, or an issue. Fetch issues through an available GitHub or Linear connector, or `gh issue view <number> --repo <owner/repo>`. If you can't reach the issue, ask for its content rather than guessing.
- Look at the relevant code, manifests, docs, schema, and deployment config before asking anything those can answer. Read `.env.example` and variable names, never secret values.
- For a new project with no stack preference, [references/recommended_stacks.md](references/recommended_stacks.md) is an opinionated starting point; verify time-sensitive choices before recommending them.

## Ask only what matters

Ask about decisions that materially change scope or implementation and that the input and codebase don't settle: who it's for and the problem, what v1 must do and must not, how success is observed, acceptance criteria and edge cases, stack or deployment constraints, and which technical choices need research. Recommend an answer for each question when the evidence supports one, and label assumptions as assumptions. A well-specified issue may need no interview at all. Use a structured question tool if the host has one; plain conversation is fine.

## Write the spec

Use [project_spec_template.md](references/project_spec_template.md) or [feature_spec_template.md](references/feature_spec_template.md). Drop sections that don't apply, mark real unknowns explicitly, and don't invent milestones to fill the template. Distinguish observed repository facts from inferred affected files or proposed architecture.

Both spec types must define **Success and Verification**: the observable successful outcome, criteria paired with suitable verification methods and explicit passing results, and end-to-end proof of the main user journey. Include important failure cases, checks for existing behavior that must not break, and any verification constraints when relevant. Keep checks proportional to the work. Distinguish planned verification from actual results; writing the spec does not establish that any check has passed. Identify criteria that would remain unverified when access, credentials, user review, or observation time is unavailable.

Project specs need two extra pieces:

- **Architecture Map** — the building blocks, a simple text diagram of how they connect, and choices marked **(research needed)**. About a page, plain English.
- **Agent Decision Boundaries** — which decisions a future coding agent may make on its own, subject to repository instructions.

Keep it concise: this is a working document, not a formal PRD.

Save to the user's path, otherwise to the existing `specs/` or `docs/` directory with a descriptive filename. Don't overwrite an existing spec unless asked to revise it.

## Finish

Link the saved spec, summarize its scope, key assumptions, and open decisions, and apply any revisions the user asks for. Suggest the `research` skill (if available) for **(research needed)** items. Writing the spec does not mean implementing it; only continue into implementation if the user asked for both.

Create Spec

Produce a working spec grounded in the user’s goal and what already exists in the repository. A project spec covers a new product or large initiative; a feature spec covers a change to something that exists. Pick by the size of the work, not by whether the input was a file or an issue.

Gather context

Input is the current request plus any invocation text: an inline idea, a local file to read, or an issue. Fetch issues through an available GitHub or Linear connector, or gh issue view <number> --repo <owner/repo>. If you can’t reach the issue, ask for its content rather than guessing.
Look at the relevant code, manifests, docs, schema, and deployment config before asking anything those can answer. Read .env.example and variable names, never secret values.
For a new project with no stack preference, references/recommended_stacks.md is an opinionated starting point; verify time-sensitive choices before recommending them.

Ask only what matters

Ask about decisions that materially change scope or implementation and that the input and codebase don’t settle: who it’s for and the problem, what v1 must do and must not, how success is observed, acceptance criteria and edge cases, stack or deployment constraints, and which technical choices need research. Recommend an answer for each question when the evidence supports one, and label assumptions as assumptions. A well-specified issue may need no interview at all. Use a structured question tool if the host has one; plain conversation is fine.

Write the spec

Use project_spec_template.md or feature_spec_template.md. Drop sections that don’t apply, mark real unknowns explicitly, and don’t invent milestones to fill the template. Distinguish observed repository facts from inferred affected files or proposed architecture.

Both spec types must define Success and Verification: the observable successful outcome, criteria paired with suitable verification methods and explicit passing results, and end-to-end proof of the main user journey. Include important failure cases, checks for existing behavior that must not break, and any verification constraints when relevant. Keep checks proportional to the work. Distinguish planned verification from actual results; writing the spec does not establish that any check has passed. Identify criteria that would remain unverified when access, credentials, user review, or observation time is unavailable.

Project specs need two extra pieces:

Architecture Map — the building blocks, a simple text diagram of how they connect, and choices marked (research needed). About a page, plain English.
Agent Decision Boundaries — which decisions a future coding agent may make on its own, subject to repository instructions.

Keep it concise: this is a working document, not a formal PRD.

Save to the user’s path, otherwise to the existing specs/ or docs/ directory with a descriptive filename. Don’t overwrite an existing spec unless asked to revise it.

Finish

Link the saved spec, summarize its scope, key assumptions, and open decisions, and apply any revisions the user asks for. Suggest the research skill (if available) for (research needed) items. Writing the spec does not mean implementing it; only continue into implementation if the user asked for both.

Project spec template

references/project_spec_template.md

Select and copy the complete source below.

# Project Spec: [Project Name]

## Project Goals
**Type:** [internal tool / personal project / public product / MVP / learning project]

**Goal statement:**
> [1-2 sentences describing the core purpose]

---

## Product Requirements

### Who is this for?
**Target user:** [specific user description]
**User context:** [when/where/why they use this]

### What problems does it solve?
1. [Problem 1]
2. [Problem 2]
3. [Problem 3]

### What should the product do?
[Core functionality description]

**Key user flows:**
- [Flow 1]
- [Flow 2]

---

## Success and Verification
_Define the proof before implementation. These are planned checks, not claims that verification has already passed. Keep criteria specific to this project's scope; omit checks that don't apply._

### Successful Outcome
[What can the user accomplish when this work is complete? Describe the observable result.]

### Verification Criteria and Methods
_Each required outcome needs a suitable check and a clear passing result. Include important failure cases as well as the happy path. If the spec spans multiple milestones, identify which milestone each criterion belongs to._

| Criterion | How to verify | Passing result |
|-----------|---------------|----------------|
| [Required behavior or outcome] | [Test, walkthrough, measurement, or review, including relevant inputs] | [Specific observable evidence or threshold] |
| [Important failure or edge case] | [How to exercise the condition] | [Expected handling and observable result] |

### End-to-End Proof
_Describe the main user journey to exercise from start to finish. Check the actual outcome, not just whether individual components pass tests._

- **Environment:** [Local / staging / production, as appropriate to the requested scope]
- **Starting state and inputs:** [Required setup and representative data]
- **Steps:** [User actions from start to finish]
- **Expected final result:** [What must be observable when the journey completes]
- **Evidence to capture:** [Relevant test output, screenshot, persisted record, measurement, or review result]

### What Must Not Break
_Existing behavior that must still work, and how to check it. Omit for a new project when nothing exists yet._

| Existing behavior | How to verify it still works |
|-------------------|------------------------------|
| [Behavior to preserve] | [Relevant regression check] |

### Verification Constraints
_Note checks that need user review, unavailable credentials, external access, or a longer observation period. If blocked, report the specific criterion that remains unverified; a substitute check does not establish the original outcome._

- [Constraint, affected criterion, and what is needed to complete verification — or "None"]

---

## Milestones

### MVP (Milestone 1)
The absolute minimum needed to validate the idea.

- [ ] [Feature]
- [ ] [Feature]
- [ ] [Feature]

**What's left out of MVP:**
- [Deferred item]

### V2 (Milestone 2)
- [ ] [Feature]
- [ ] [Feature]

### Future Versions
- [Ideas for later]

---

## Engineering Requirements

### Tech Stack
| Component | Choice | Notes |
|-----------|--------|-------|
| Language | | |
| Framework | | |
| Styling | | |
| Database | | |
| Auth | | |
| Hosting | | |
| Other | | |

### Architecture Map
A one-page view of the system: the building blocks and how they connect. Mark any uncertain choice with **(research needed)**.

**System overview:**
> [High-level description of how pieces fit together]

**Building blocks:** (include only what this project needs)
- **Frontend:** [what the user sees and does]
- **Backend:** [API routes / business logic]
- **Database:** [what the app needs to remember]
- **Auth:** [how users sign in, if accounts are needed]
- **File storage:** [user uploads or generated files, if any]
- **External services:** [third-party APIs, AI models, payments, email]

**How the blocks connect:**
```
User → Frontend → Backend API → Database
                      ↘ [External service] ([purpose])
```

**Research needed:**
- [Uncertain choice + what to find out — e.g., "Auth: Supabase Auth vs. Clerk"]

**Open questions:**
- [Decision to make before building]

### Database Schema (initial)
> [Main entities/tables and key fields]

### API Design (if applicable)
> [Main endpoints or API approach]

### Infrastructure to Provision
- [ ] [Service/resource needed before building]

---

## Out of Scope
- [Explicit exclusion 1]
- [Explicit exclusion 2]

---

## Agent Decision Boundaries
The coding agent may make the following decisions without additional confirmation, subject to repository instructions and approval policies:
- [e.g., Database schema details]
- [e.g., API design]
- [e.g., Component structure]
- [e.g., Error handling approach]

Project Spec: [Project Name]

Project Goals

Type: [internal tool / personal project / public product / MVP / learning project]

Goal statement:

[1-2 sentences describing the core purpose]

Product Requirements

Who is this for?

Target user: [specific user description] User context: [when/where/why they use this]

What problems does it solve?

[Problem 1]
[Problem 2]
[Problem 3]

What should the product do?

[Core functionality description]

Key user flows:

[Flow 1]
[Flow 2]

Success and Verification

Define the proof before implementation. These are planned checks, not claims that verification has already passed. Keep criteria specific to this project’s scope; omit checks that don’t apply.

Successful Outcome

[What can the user accomplish when this work is complete? Describe the observable result.]

Verification Criteria and Methods

Each required outcome needs a suitable check and a clear passing result. Include important failure cases as well as the happy path. If the spec spans multiple milestones, identify which milestone each criterion belongs to.

Criterion	How to verify	Passing result
[Required behavior or outcome]	[Test, walkthrough, measurement, or review, including relevant inputs]	[Specific observable evidence or threshold]
[Important failure or edge case]	[How to exercise the condition]	[Expected handling and observable result]

End-to-End Proof

Describe the main user journey to exercise from start to finish. Check the actual outcome, not just whether individual components pass tests.

Environment: [Local / staging / production, as appropriate to the requested scope]
Starting state and inputs: [Required setup and representative data]
Steps: [User actions from start to finish]
Expected final result: [What must be observable when the journey completes]
Evidence to capture: [Relevant test output, screenshot, persisted record, measurement, or review result]

What Must Not Break

Existing behavior that must still work, and how to check it. Omit for a new project when nothing exists yet.

Existing behavior	How to verify it still works
[Behavior to preserve]	[Relevant regression check]

Verification Constraints

Note checks that need user review, unavailable credentials, external access, or a longer observation period. If blocked, report the specific criterion that remains unverified; a substitute check does not establish the original outcome.

[Constraint, affected criterion, and what is needed to complete verification — or “None”]

Milestones

MVP (Milestone 1)

The absolute minimum needed to validate the idea.

[Feature]
[Feature]
[Feature]

What’s left out of MVP:

[Deferred item]

V2 (Milestone 2)

[Feature]
[Feature]

Future Versions

[Ideas for later]

Engineering Requirements

Tech Stack

Component	Choice	Notes
Language
Framework
Styling
Database
Auth
Hosting
Other

Architecture Map

A one-page view of the system: the building blocks and how they connect. Mark any uncertain choice with (research needed).

System overview:

[High-level description of how pieces fit together]

Building blocks: (include only what this project needs)

Frontend: [what the user sees and does]
Backend: [API routes / business logic]
Database: [what the app needs to remember]
Auth: [how users sign in, if accounts are needed]
File storage: [user uploads or generated files, if any]
External services: [third-party APIs, AI models, payments, email]

How the blocks connect:

User → Frontend → Backend API → Database
                      ↘ [External service] ([purpose])

Research needed:

[Uncertain choice + what to find out — e.g., “Auth: Supabase Auth vs. Clerk”]

Open questions:

[Decision to make before building]

Database Schema (initial)

[Main entities/tables and key fields]

API Design (if applicable)

[Main endpoints or API approach]

Infrastructure to Provision

[Service/resource needed before building]

Out of Scope

[Explicit exclusion 1]
[Explicit exclusion 2]

Agent Decision Boundaries

The coding agent may make the following decisions without additional confirmation, subject to repository instructions and approval policies:

[e.g., Database schema details]
[e.g., API design]
[e.g., Component structure]
[e.g., Error handling approach]

Feature spec template

references/feature_spec_template.md

Select and copy the complete source below.

# Feature Spec: [Feature Name]

**Source:** [issue link]
**Status:** Draft

---

## Overview
> [Brief description of the feature and why it's needed]

## Requirements
- [Functional requirement 1]
- [Functional requirement 2]
- [Functional requirement 3]

## Success and Verification
_Define the proof before implementation. These are planned checks, not claims that verification has already passed. Keep criteria specific to this feature's scope; omit checks that don't apply._

### Successful Outcome
[What can the user accomplish when this work is complete? Describe the observable result.]

### Verification Criteria and Methods
_Each required outcome needs a suitable check and a clear passing result. Include important failure cases as well as the happy path. Reference the Edge Cases section where relevant so expected behavior and verification stay aligned._

| Criterion | How to verify | Passing result |
|-----------|---------------|----------------|
| [Required behavior or outcome] | [Test, walkthrough, measurement, or review, including relevant inputs] | [Specific observable evidence or threshold] |
| [Important failure or edge case] | [How to exercise the condition] | [Expected handling and observable result] |

### End-to-End Proof
_Describe the main user journey to exercise from start to finish. Check the actual outcome, not just whether individual components pass tests._

- **Environment:** [Local / staging / production, as appropriate to the requested scope]
- **Starting state and inputs:** [Required setup and representative data]
- **Steps:** [User actions from start to finish]
- **Expected final result:** [What must be observable when the journey completes]
- **Evidence to capture:** [Relevant test output, screenshot, persisted record, measurement, or review result]

### What Must Not Break
_Existing behavior that must still work, and how to check it. Omit for a new project when nothing exists yet._

| Existing behavior | How to verify it still works |
|-------------------|------------------------------|
| [Behavior to preserve] | [Relevant regression check] |

### Verification Constraints
_Note checks that need user review, unavailable credentials, external access, or a longer observation period. If blocked, report the specific criterion that remains unverified; a substitute check does not establish the original outcome._

- [Constraint, affected criterion, and what is needed to complete verification — or "None"]

## Edge Cases
| Scenario | Expected Behavior |
|----------|-------------------|
| [Edge case 1] | [How to handle] |
| [Edge case 2] | [How to handle] |

## UI/UX Notes
> [Design considerations, if applicable]

## Technical Approach

### Scope of Changes
> [High-level areas and likely affected files. Label confirmed repository evidence separately from inferred scope.]

### API Changes
> [New or modified endpoints, if any]

### Schema Changes
> [New or modified tables/fields, if any]

### Implementation Notes
> [Key decisions, patterns to follow, gotchas]

## Not in Scope
- [Explicit exclusion for this feature]

Feature Spec: [Feature Name]

Source: [issue link] Status: Draft

Overview

[Brief description of the feature and why it’s needed]

Requirements

[Functional requirement 1]
[Functional requirement 2]
[Functional requirement 3]

Success and Verification

Define the proof before implementation. These are planned checks, not claims that verification has already passed. Keep criteria specific to this feature’s scope; omit checks that don’t apply.

Successful Outcome

[What can the user accomplish when this work is complete? Describe the observable result.]

Verification Criteria and Methods

Each required outcome needs a suitable check and a clear passing result. Include important failure cases as well as the happy path. Reference the Edge Cases section where relevant so expected behavior and verification stay aligned.

Criterion	How to verify	Passing result
[Required behavior or outcome]	[Test, walkthrough, measurement, or review, including relevant inputs]	[Specific observable evidence or threshold]
[Important failure or edge case]	[How to exercise the condition]	[Expected handling and observable result]

End-to-End Proof

Describe the main user journey to exercise from start to finish. Check the actual outcome, not just whether individual components pass tests.

Environment: [Local / staging / production, as appropriate to the requested scope]
Starting state and inputs: [Required setup and representative data]
Steps: [User actions from start to finish]
Expected final result: [What must be observable when the journey completes]
Evidence to capture: [Relevant test output, screenshot, persisted record, measurement, or review result]

What Must Not Break

Existing behavior that must still work, and how to check it. Omit for a new project when nothing exists yet.

Existing behavior	How to verify it still works
[Behavior to preserve]	[Relevant regression check]

Verification Constraints

[Constraint, affected criterion, and what is needed to complete verification — or “None”]

Edge Cases

Scenario	Expected Behavior
[Edge case 1]	[How to handle]
[Edge case 2]	[How to handle]

UI/UX Notes

[Design considerations, if applicable]

Technical Approach

Scope of Changes

[High-level areas and likely affected files. Label confirmed repository evidence separately from inferred scope.]

API Changes

[New or modified endpoints, if any]

Schema Changes

[New or modified tables/fields, if any]

Implementation Notes

[Key decisions, patterns to follow, gotchas]

Not in Scope

[Explicit exclusion for this feature]

Recommended technology stacks

references/recommended_stacks.md

Select and copy the complete source below.

# Recommended Tech Stacks

Opinionated starting points for projects without an established stack. Existing repository conventions and user preferences take precedence. Verify current compatibility, pricing, and availability before recommending a time-sensitive choice.

## General (All App Types)

| Layer | Tool | URL |
|-------|------|-----|
| Project management | GitHub Issues | https://github.com |
| Project management (alt) | Linear | https://linear.app |

---

## Mobile App

Native iOS or cross-platform mobile app that lives on a device.

| Layer | Tool | URL |
|-------|------|-----|
| Cross-platform framework | Expo | https://expo.dev |
| Native iOS | Xcode | https://developer.apple.com/xcode |
| Analytics | PostHog | https://posthog.com |

---

## Full Stack Web App

The "one framework does everything" approach. Next.js can handle frontend, backend, and API routes in a single codebase. Whether this is the simplest choice depends on the project.

| Layer | Tool | URL |
|-------|------|-----|
| Hosting | Vercel or Cloudflare | https://vercel.com / https://www.cloudflare.com |
| Framework | Next.js | https://nextjs.org |
| UI components | Shadcn/ui | https://ui.shadcn.com |
| Styling | Tailwind CSS | https://tailwindcss.com |
| Database | Supabase | https://supabase.com |
| Auth / Login | Clerk | https://clerk.com |
| Email | Resend | https://resend.com |
| Analytics | PostHog | https://posthog.com |

---

## AI App

Any app that uses an LLM or AI image model.

| Layer | Tool | URL |
|-------|------|-----|
| Model API/provider | Choose during project research based on required modalities, cost, privacy, and current availability | |
| Image model/provider | Choose during project research when image generation is required | |


---

## AI Agent App

An agent where the LLM takes actions in a loop — receives a goal, decides what to do, observes the result, repeats.

**For beginners:** Use Claude Code or Codex as a development agent to prototype and verify the workflow. A deployed agent product still needs an explicit model API/provider and an appropriate runtime or SDK; do not treat the development tool itself as the production runtime.

Recommended Tech Stacks

Opinionated starting points for projects without an established stack. Existing repository conventions and user preferences take precedence. Verify current compatibility, pricing, and availability before recommending a time-sensitive choice.

General (All App Types)

Layer	Tool	URL
Project management	GitHub Issues	https://github.com
Project management (alt)	Linear	https://linear.app

Mobile App

Native iOS or cross-platform mobile app that lives on a device.

Layer	Tool	URL
Cross-platform framework	Expo	https://expo.dev
Native iOS	Xcode	https://developer.apple.com/xcode
Analytics	PostHog	https://posthog.com

Full Stack Web App

The “one framework does everything” approach. Next.js can handle frontend, backend, and API routes in a single codebase. Whether this is the simplest choice depends on the project.

Layer	Tool	URL
Hosting	Vercel or Cloudflare	https://vercel.com / https://www.cloudflare.com
Framework	Next.js	https://nextjs.org
UI components	Shadcn/ui	https://ui.shadcn.com
Styling	Tailwind CSS	https://tailwindcss.com
Database	Supabase	https://supabase.com
Auth / Login	Clerk	https://clerk.com
Email	Resend	https://resend.com
Analytics	PostHog	https://posthog.com

AI App

Any app that uses an LLM or AI image model.

Layer	Tool	URL
Model API/provider	Choose during project research based on required modalities, cost, privacy, and current availability
Image model/provider	Choose during project research when image generation is required

AI Agent App

An agent where the LLM takes actions in a loop — receives a goal, decides what to do, observes the result, repeats.

For beginners: Use Claude Code or Codex as a development agent to prototype and verify the workflow. A deployed agent product still needs an explicit model API/provider and an appropriate runtime or SDK; do not treat the development tool itself as the production runtime.

Brainstorm skill Install both planning skills

Use Avthar's Skills and templates in your next project

When to use it

How it works

Read the context

Resolve important gaps

Save the spec

What you get

You’re ready to move on when…

Full instructions & templates

Create Spec

Gather context

Ask only what matters

Write the spec

Finish

Project Spec: [Project Name]

Project Goals

Product Requirements

Who is this for?

What problems does it solve?

What should the product do?

Success and Verification

Successful Outcome

Verification Criteria and Methods

End-to-End Proof

What Must Not Break

Verification Constraints

Milestones

MVP (Milestone 1)

V2 (Milestone 2)

Future Versions

Engineering Requirements

Tech Stack

Architecture Map

Database Schema (initial)

API Design (if applicable)

Infrastructure to Provision

Out of Scope

Agent Decision Boundaries

Feature Spec: [Feature Name]

Overview

Requirements

Success and Verification

Successful Outcome

Verification Criteria and Methods

End-to-End Proof

What Must Not Break

Verification Constraints

Edge Cases

UI/UX Notes

Technical Approach

Scope of Changes

API Changes

Schema Changes

Implementation Notes

Not in Scope

Recommended Tech Stacks

General (All App Types)

Mobile App

Full Stack Web App

AI App

AI Agent App

Get the full AI Playbook