AI agent skills for startup validation, competitive intelligence, and planning
ai-agentsbattle-cardsclaude-codeclaude-skillscompetitive-analysiscompetitive-intelligencemarket-researchpricing-analysisstartupstartup-validation
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.ymlnew file mode 100644index 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: falsediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 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 skilldiff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.ymlnew file mode 100644index 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: falsediff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.mdnew file mode 100644index 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 credentialsdiff --git a/.github/PULL_REQUEST_TEMPLATE/skill-improvement.md b/.github/PULL_REQUEST_TEMPLATE/skill-improvement.mdnew file mode 100644index 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 minimaldiff --git a/.gitignore b/.gitignorenew file mode 100644index 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+.envdiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 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 amenddiff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 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.mdnew file mode 100644index 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/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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