Skip to content

AI agent skills for startup validation, competitive intelligence, and planning

Add repo structure: README, CLAUDE.md, AGENTS.md, LICENSE, GitHub templates

Ferdinando Bonsegnad1e55af04a6f
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
new file mode 100644
index 0000000..9f68333
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,48 @@
+name: Bug Report
+description: Report an issue with the startup-design skill
+title: "Bug: [brief description]"
+labels: ["bug"]
+body:
+ - type: textarea
+ id: description
+ attributes:
+ label: What happened?
+ description: Describe the issue you encountered
+ placeholder: "When I tried to..."
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ description: What did you expect to happen?
+ validations:
+ required: true
+
+ - type: dropdown
+ id: phase
+ attributes:
+ label: Which phase?
+ description: Which phase of the skill was affected?
+ options:
+ - Phase 0 (Resume Check)
+ - Phase 1 (Intake Interview)
+ - Phase 2 (Brainstorm)
+ - Phase 3 (Market Research)
+ - Phase 4 (Strategy)
+ - Phase 5 (Brand)
+ - Phase 6 (Product)
+ - Phase 7 (Financial)
+ - Phase 8 (Validation)
+ - Not sure
+ validations:
+ required: true
+
+ - type: input
+ id: agent
+ attributes:
+ label: AI agent used
+ placeholder: "Claude Code, Cursor, etc."
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..3a43744
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Contributing Guide
+ url: https://github.com/ferdinandobons/startup-skill/blob/main/CONTRIBUTING.md
+ about: How to contribute improvements to this skill
diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml
new file mode 100644
index 0000000..2178d20
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/improvement.yml
@@ -0,0 +1,41 @@
+name: Improvement Request
+description: Suggest an improvement to the skill
+title: "Improvement: [brief description]"
+labels: ["enhancement"]
+body:
+ - type: textarea
+ id: description
+ attributes:
+ label: What would you like to improve?
+ description: Describe the improvement you'd like to see
+ placeholder: "It would be better if..."
+ validations:
+ required: true
+
+ - type: dropdown
+ id: area
+ attributes:
+ label: Area
+ description: Which part of the skill?
+ options:
+ - Intake Interview
+ - Brainstorming
+ - Market Research / Agents
+ - Strategy Frameworks
+ - Brand
+ - Product
+ - Financial
+ - Validation
+ - Output Format
+ - Progress Tracking
+ - Other
+ validations:
+ required: true
+
+ - type: textarea
+ id: examples
+ attributes:
+ label: Examples
+ description: Provide examples of how this improvement would work
+ validations:
+ required: false
diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md
new file mode 100644
index 0000000..2385229
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md
@@ -0,0 +1,15 @@
+## Documentation
+
+## Summary
+
+<!-- What documentation changes are you making? -->
+
+## Files changed
+
+<!-- List the files you're updating -->
+
+## Checklist
+
+- [ ] Links are valid
+- [ ] Formatting is consistent
+- [ ] No sensitive data or credentials
diff --git a/.github/PULL_REQUEST_TEMPLATE/skill-improvement.md b/.github/PULL_REQUEST_TEMPLATE/skill-improvement.md
new file mode 100644
index 0000000..712c0de
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/skill-improvement.md
@@ -0,0 +1,21 @@
+## Skill Improvement
+
+## Summary
+
+<!-- What are you changing and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] Improved instructions
+- [ ] New/updated reference files
+- [ ] Research agent improvements
+- [ ] New eval cases
+
+## Checklist
+
+- [ ] `SKILL.md` is under 500 lines
+- [ ] YAML frontmatter is valid
+- [ ] No sensitive data or credentials
+- [ ] Tested locally with AI agent
+- [ ] Changes are focused and minimal
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..5795bea
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,18 @@
+# Skill workspace (test results, iterations, benchmarks)
+startup-design-workspace/
+
+# OS files
+.DS_Store
+*.swp
+*~
+
+# Claude Code
+.claude/
+
+# Node
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+.env
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..77a1304
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,79 @@
+# AGENTS.md
+
+Guidelines for AI agents working in this repository.
+
+## Repository Overview
+
+This repository contains the **startup-design** skill — a comprehensive startup design and idea validation workflow for AI agents.
+
+- **Name**: Startup Design Skill
+- **GitHub**: [ferdinandobons/startup-skill](https://github.com/ferdinandobons/startup-skill)
+- **Creator**: Ferdinando Bons
+- **License**: MIT
+
+## Repository Structure
+
+```
+startup-skill/
+├── startup-design/
+│ ├── SKILL.md # Main skill file (~495 lines)
+│ └── references/ # Supporting documents (loaded on demand)
+│ ├── research-principles.md # ~60 lines
+│ ├── research-wave-1-market.md # ~130 lines
+│ ├── research-wave-2-competitors.md # ~170 lines
+│ ├── research-wave-3-customers.md # ~170 lines
+│ ├── research-wave-4-distribution.md # ~110 lines
+│ ├── research-synthesis.md # ~90 lines
+│ └── frameworks.md # ~110 lines
+├── CLAUDE.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+## Skill Specification
+
+The skill follows standard SKILL.md format with YAML frontmatter:
+
+```yaml
+---
+name: startup-design
+description: Design, validate, and plan a startup from scratch...
+---
+```
+
+### Frontmatter Constraints
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | 1-64 chars, lowercase `a-z`, numbers, hyphens. Must match directory name. |
+| `description` | Yes | 1-1024 chars. Include trigger phrases. |
+
+### Progressive Loading
+
+Reference files are loaded on demand — only read the file needed for the current phase:
+- Phase 3 Wave 1: read `research-principles.md` + `research-wave-1-market.md`
+- Phase 3 Wave 2: read `research-wave-2-competitors.md`
+- Phase 4: read `frameworks.md`
+- Never load all reference files at once
+
+## Writing Style
+
+- Direct and instructional
+- Specific over vague — quantify everything
+- Honest over encouraging — surface real risks
+- Actionable — every section should tell the founder what to do next
+- No filler or generic platitudes
+
+## Testing
+
+Eval cases are in `startup-design-workspace/evals/evals.json` (5 test cases). Run evals by:
+1. Spawning an agent with the eval prompt
+2. Grading outputs against assertions
+3. Comparing with/without skill results
+
+## Git Workflow
+
+- Branch naming: `feature/`, `fix/`, `docs/`
+- Commit messages: conventional commits (`feat:`, `fix:`, `docs:`, `test:`)
+- Always create new commits, never amend
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..14224ca
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+Guidelines for AI agents working in this repository.
+
+## Repository Overview
+
+This repository contains the **startup-design** skill for AI agents. The skill guides comprehensive startup design and idea validation through 8 structured phases.
+
+- **Name**: Startup Design Skill
+- **GitHub**: [ferdinandobons/startup-skill](https://github.com/ferdinandobons/startup-skill)
+- **Creator**: Ferdinando Bons
+- **License**: MIT
+
+## Repository Structure
+
+```
+startup-skill/
+├── startup-design/
+│ ├── SKILL.md # Main skill file (~495 lines, 8 phases)
+│ └── references/ # Supporting documents loaded on demand
+│ ├── research-principles.md
+│ ├── research-wave-1-market.md
+│ ├── research-wave-2-competitors.md
+│ ├── research-wave-3-customers.md
+│ ├── research-wave-4-distribution.md
+│ ├── research-synthesis.md
+│ └── frameworks.md
+├── CLAUDE.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+## Key Conventions
+
+### Skill Format
+
+- `SKILL.md` uses YAML frontmatter with `name` and `description` fields
+- `name` must match directory name exactly (lowercase, hyphens)
+- `description` must be 1-1024 characters with trigger phrases
+- Keep `SKILL.md` under 500 lines; move details to `references/`
+- References are loaded progressively (only when needed for current phase)
+
+### Research Architecture
+
+Phase 3 (Market Research) uses 4 sequential waves of parallel agents:
+- Wave 1: Market Landscape (3 agents)
+- Wave 2: Competitive Analysis (3 agents)
+- Wave 3: Customer & Demand (3 agents)
+- Wave 4: Distribution (2 agents)
+
+Each wave must complete before the next starts. Agents use WebSearch for real data.
+
+### Output Structure
+
+The skill generates files in subdirectories:
+- `00-intake/` — Brief, brainstorm
+- `01-discovery/` — Market research (raw + synthesized)
+- `02-strategy/` — Lean canvas, positioning, business model, GTM
+- `03-brand/` — Mission, vision, tone of voice
+- `04-product/` — MVP, features, user journey
+- `05-financial/` — Revenue, costs, projections
+- `06-validation/` — Experiments, risks, scorecard
+
+### Testing
+
+Eval cases are in `startup-design-workspace/evals/evals.json`. To test:
+1. Run each eval prompt through the skill
+2. Grade against assertions in `eval_metadata.json`
+3. Compare with/without skill performance
+
+## Git Workflow
+
+### Commit Messages
+
+Follow conventional commits:
+- `feat: add new phase or capability`
+- `fix: improve skill instructions`
+- `docs: update README or CLAUDE.md`
+- `test: add or update eval cases`
+
+### Branch Naming
+
+- `feature/description`
+- `fix/description`
+- `docs/description`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..027ae4f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,76 @@
+# Contributing
+
+Thanks for your interest in contributing to Startup Design Skill! This guide will help you improve the skill or add new capabilities.
+
+## Ways to Contribute
+
+- **Improve skill instructions** — Make phases clearer, fix edge cases
+- **Add reference files** — New frameworks, research templates
+- **Improve research agents** — Better search queries, output formats
+- **Add eval cases** — New test scenarios for different startup types
+- **Fix bugs** — Report or fix issues with the skill
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork
+3. Create a feature branch (`git checkout -b feature/your-improvement`)
+
+## Skill Structure
+
+```
+startup-design/
+├── SKILL.md # Main skill file (keep under 500 lines)
+└── references/ # Supporting documents loaded on demand
+ ├── research-principles.md
+ ├── research-wave-*.md
+ ├── research-synthesis.md
+ └── frameworks.md
+```
+
+### Guidelines
+
+- **SKILL.md** should stay under 500 lines. Move detailed content to `references/`
+- **Reference files** should be self-contained and loaded only when needed
+- **YAML frontmatter** must have valid `name` and `description` fields
+- `name` must match directory name exactly (lowercase, hyphens only)
+- `description` should include trigger phrases for skill discovery
+
+## Testing Your Changes
+
+1. Start a conversation with Claude Code in the repo directory
+2. Test with different startup ideas (vague, detailed, non-English)
+3. Verify the skill triggers correctly
+4. Check that outputs follow the expected directory structure
+5. Confirm PROGRESS.md is updated properly
+
+### Eval Cases
+
+Existing test scenarios are in `startup-design-workspace/evals/evals.json`:
+
+| Test | Scenario | Phases Tested |
+|------|----------|---------------|
+| 1 | Vague idea (mechanic app) | Phase 1 |
+| 2 | Detailed B2B (invoice AI) | Phase 1 + 2 |
+| 3 | Italian language (food marketplace) | Phase 1 |
+| 4 | Validation focus (Slack extension) | Phase 1 + 2 |
+| 5 | Checkpoint resume (parking app) | Phase 4 |
+
+## Submitting Your Contribution
+
+1. Make your changes
+2. Test locally with an AI agent
+3. Submit a pull request using the appropriate template
+
+## Quality Checklist
+
+- [ ] `SKILL.md` is under 500 lines
+- [ ] YAML frontmatter is valid
+- [ ] `name` matches directory name
+- [ ] No sensitive data or credentials
+- [ ] Tested locally with AI agent
+- [ ] Changes are focused and minimal
+
+## Questions?
+
+Open an issue if you have questions or need help with your contribution.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..2ef008a
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ferdinando Bons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..841a7ad
--- /dev/null
+++ b/README.md
@@ -0,0 +1,138 @@
+# Startup Design Skill
+
+An AI agent skill for comprehensive startup design and idea validation. Takes a raw idea from concept to validated business plan through structured research, strategic frameworks, and honest assessment.
+
+Built for founders, solopreneurs, and product people who want to validate ideas rigorously before investing time and money. Works with [Claude Code](https://claude.ai/claude-code) and any agent that supports skills.
+
+**Contributions welcome!** Found a way to improve the skill or have a new idea? [Open a PR](#contributing).
+
+Run into a problem or have a question? [Open an issue](https://github.com/ferdinandobons/startup-skill/issues).
+
+## What It Does
+
+The skill guides an AI agent through 8 structured phases, producing a complete set of markdown documents:
+
+```
+INTAKE -> BRAINSTORM -> RESEARCH -> STRATEGY -> BRAND -> PRODUCT -> FINANCIAL -> VALIDATION
+```
+
+Each phase builds on the previous one. Sessions can be interrupted and resumed from checkpoints.
+
+### Phases
+
+| Phase | What It Produces | Key Output Files |
+|-------|-----------------|-----------------|
+| 1. Intake Interview | Deep understanding of the idea, founder, and constraints | `00-intake/brief.md` |
+| 2. Brainstorm | 5-8 variations of the idea before committing | `00-intake/brainstorm.md` |
+| 3. Market Research | Multi-agent web research in 4 waves (11 agents) | `01-discovery/*.md` |
+| 4. Strategy | Lean Canvas, positioning, business model, GTM | `02-strategy/*.md` |
+| 5. Brand | Mission, vision, tone of voice, personality | `03-brand/*.md` |
+| 6. Product | MVP definition, feature prioritization, user journey | `04-product/*.md` |
+| 7. Financial | Revenue model, cost structure, projections | `05-financial/*.md` |
+| 8. Validation | Experiments, risk analysis, scorecard | `06-validation/*.md` |
+
+### Modes
+
+- **Full Mode** (default): All 8 phases, thorough analysis
+- **Fast Track**: Compressed version for quick go/no-go decisions
+
+### Features
+
+- Multi-language support (auto-detects from user input, defaults to English)
+- Progress tracking via `PROGRESS.md` for session resumption
+- Multi-agent parallel web research with source quality tiers
+- Strategic frameworks: Lean Canvas, April Dunford Positioning, Value Proposition Canvas, RICE/MoSCoW
+- Honest assessment with risk analysis and validation experiments
+
+## Installation
+
+### Claude Code
+
+Add as a plugin:
+
+```bash
+# From the Claude Code CLI
+/install-plugin ferdinandobons/startup-skill
+```
+
+Or clone and use directly:
+
+```bash
+git clone https://github.com/ferdinandobons/startup-skill.git
+cd startup-skill
+```
+
+### Other Agents
+
+Copy the `startup-design/` directory into your agent's skills folder. The skill follows the standard `SKILL.md` format with `references/` for supplementary documents.
+
+## Usage
+
+Start a conversation with your AI agent and describe your startup idea:
+
+```
+I have an idea for a SaaS that helps real estate agents automate their follow-up emails using AI.
+I've been an agent for 12 years and I know the pain. Can you help me figure out if it's worth building?
+```
+
+The skill will automatically trigger and guide you through the intake interview, then proceed phase by phase.
+
+To resume a previous session:
+
+```
+Resume from checkpoint
+```
+
+For a quick validation:
+
+```
+I need a quick validation of this idea: [your idea]. Fast track mode.
+```
+
+## Repository Structure
+
+```
+startup-skill/
+├── startup-design/
+│ ├── SKILL.md # Main skill file (8 phases)
+│ └── references/
+│ ├── research-principles.md # Cross-cutting research rules
+│ ├── research-wave-1-market.md # Market sizing agents
+│ ├── research-wave-2-competitors.md # Competitive analysis agents
+│ ├── research-wave-3-customers.md # Customer research agents
+│ ├── research-wave-4-distribution.md # Distribution agents
+│ ├── research-synthesis.md # How to synthesize findings
+│ └── frameworks.md # Strategic frameworks
+├── CLAUDE.md # Agent guidelines
+├── CONTRIBUTING.md # How to contribute
+├── LICENSE # MIT License
+└── README.md # This file
+```
+
+## Eval Results
+
+The skill has been tested across 5 eval scenarios comparing skill-guided output vs. baseline:
+
+| Metric | With Skill | Without Skill |
+|--------|-----------|---------------|
+| Assertion Pass Rate | 100% (21/21) | 57% (12/21) |
+| Structured Output | Always | Rarely |
+| Interview Process | Multi-round, targeted | Single dump |
+| Brainstorming | 5-8 variations | Skipped |
+| Progress Tracking | Always | Never |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.
+
+### Quick Start
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/improvement-name`)
+3. Make your changes
+4. Test with an AI agent
+5. Submit a pull request
+
+## License
+
+[MIT](LICENSE)
diff --git a/startup-design/SKILL.md b/startup-design/SKILL.md
index bbded22..b28064c 100644
--- a/startup-design/SKILL.md
+++ b/startup-design/SKILL.md
@@ -1,6 +1,6 @@
---
name: startup-design
-description: Comprehensive startup design and idea validation — from market research to brand identity to financial projections. Use this skill whenever the user wants to design a startup, validate a business idea, create a business plan, define brand positioning, analyze a market opportunity, or build a go-to-market strategy. Also trigger when the user mentions startup, business idea, business plan, market research, lean canvas, value proposition, MVP, go-to-market, brand identity, competitive analysis, or wants to evaluate whether an idea is worth pursuing. Even if the user just says I have an idea for — this skill applies.
+description: Design, validate, and plan a startup from scratch. Covers market research, competitive analysis, business model, brand identity, product definition, financial projections, and validation experiments. Trigger when the user has a startup idea to explore, wants to validate a business concept, needs a business plan or lean canvas, asks for market sizing or competitive landscape, wants brand positioning or go-to-market strategy, or says anything like "I have an idea for..." or "is this idea worth pursuing". Also handles resuming from a previous checkpoint.
---
# Startup Design