AI agent skills for startup validation, competitive intelligence, and planning
CLAUDE.md
Guidelines for AI agents working in this repository.
Repository Overview
This repository contains the startup plugin for AI agents. The plugin namespace is startup, and it includes multiple skills organized in 3 categories: Design, Analyze, and Build (4 skills total).
- Name: Startup Skills
- GitHub: ferdinandobons/startup-skill
- Creator: Ferdinando Bons
- License: MIT
Skill Taxonomy
| Category | Purpose | Skills |
|---|---|---|
| Design | Full process, idea to validated plan | startup-design |
| Analyze | Deep standalone analysis of one area | startup-competitors, startup-positioning |
| Build | Post-validation execution tools | startup-pitch |
Repository Structure
startup-skill/ # Plugin namespace (startup:*)
├── .claude-plugin/
│ └── marketplace.json # Plugin definition (name must be "startup")
├── startup-design/ # Skill: startup:startup-design
│ ├── SKILL.md # Main skill file (~476 lines, 8 phases + pre-flight & customer discovery)
│ └── references/ # Supporting documents loaded on demand
│ ├── research-principles.md
│ ├── research-scaling.md
│ ├── research-wave-1-market.md
│ ├── research-wave-2-competitors.md
│ ├── research-wave-3-customers.md
│ ├── research-wave-4-distribution.md
│ ├── research-synthesis.md
│ ├── verification-agent.md
│ ├── customer-interview.md
│ ├── intake-questions.md
│ ├── output-specs.md
│ ├── frameworks.md
│ ├── industry-benchmarks.md
│ ├── honesty-protocol.md
│ └── output-guidelines.md
├── startup-competitors/ # Skill: startup:startup-competitors
│ ├── SKILL.md # Main skill file (~268 lines, 3 waves)
│ └── references/
│ ├── research-principles.md
│ ├── research-scaling.md
│ ├── research-wave-1-profiles-pricing.md
│ ├── research-wave-2-sentiment-mining.md
│ ├── research-wave-3-gtm-signals.md
│ ├── research-synthesis.md
│ ├── verification-agent.md
│ └── honesty-protocol.md
├── startup-positioning/ # Skill: startup:startup-positioning
│ ├── SKILL.md # Main skill file (~302 lines, 2 waves)
│ └── references/
│ ├── research-principles.md
│ ├── research-scaling.md
│ ├── research-wave-1-alternatives.md
│ ├── research-wave-2-market-frame.md
│ ├── research-synthesis.md
│ ├── verification-agent.md
│ ├── frameworks.md
│ └── honesty-protocol.md
├── startup-pitch/ # Skill: startup:startup-pitch
│ ├── SKILL.md # Main skill file (~424 lines, 2 waves)
│ └── references/
│ ├── research-principles.md
│ ├── research-scaling.md
│ ├── research-wave-1-audience-narrative.md
│ ├── research-wave-2-competitive-framing.md
│ ├── research-synthesis.md
│ ├── verification-agent.md
│ ├── pitch-frameworks.md
│ └── honesty-protocol.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md
Key Conventions
Naming Convention
- Plugin name (
startup): defined in.claude-plugin/marketplace.json→ becomes the namespace prefix - Skill name (
startup-design,startup-competitors): defined inSKILL.mdfrontmatter → must match directory name - Command:
/startup:startup-design,/startup:startup-competitors,/startup:startup-positioning,/startup:startup-pitch—plugin-name:skill-name - Future skills go in the same repo as separate directories
Skill Format
SKILL.mduses YAML frontmatter withnameanddescriptionfieldsnamemust match directory name exactly (lowercase, hyphens)descriptionmust be 1-1024 characters with trigger phrases- Keep
SKILL.mdunder 500 lines; move details toreferences/ - References are loaded progressively (only when needed for current phase)
- Reference files use
research-wave-N-prefix for consistency across skills
Research Architecture
startup-design Phase 3 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)
startup-competitors uses 3 sequential waves of parallel agents:
- Wave 1: Competitor Profiles + Pricing Intelligence (2 agents)
- Wave 2: Customer Sentiment Mining (2 agents)
- Wave 3: GTM & Strategic Signals (2 agents)
startup-positioning uses 2 sequential waves of parallel agents:
- Wave 1: Competitive Alternatives + Customer Intelligence (2 agents)
- Wave 2: Market Frame + Trends (2 agents)
startup-pitch uses 2 sequential waves of parallel agents:
- Wave 1: Audience & Narrative Intelligence (2 agents)
- Wave 2: Competitive Framing & Why Now (2 agents)
Each wave must complete before the next starts. Agents use WebSearch for real data. All skills support Claude.ai (sequential fallback) and Knowledge-Based Mode when WebSearch is unavailable.
Research Scaling: All skills dynamically adjust research depth. After intake, a complexity score (3-9) maps to Light/Standard/Deep tiers, changing agent count and search rounds per wave. Users can override. See each skill's references/research-scaling.md.
Verification Agent: All skills run a V1: Verification agent after synthesis. It audits deliverables for consistency, unlabeled claims, and skill-specific coherence. Critical issues pause for user review. See each skill's references/verification-agent.md.
Output Structure
startup-design generates files in subdirectories:
00-intake/— Brief, brainstorm, preflight, customer interviews01-discovery/— Market research (raw + synthesized)02-strategy/— Lean canvas, positioning, business model, GTM03-brand/— Mission, vision, tone of voice04-product/— MVP, features, user journey05-financial/— Revenue, costs, projections06-validation/— Experiments, risks, scorecard
startup-competitors generates files in {project-name}/:
intake.md— Product and market contextcompetitors-report.md— Main deliverable with strategic analysiscompetitive-matrix.md— Feature comparison tablepricing-landscape.md— Pricing analysis and positioningbattle-cards/{competitor}.md— Per-competitor one-pagersraw/— Raw research data from each wave
startup-positioning generates files in {project-name}/:
intake.md— Product and market contextpositioning-doc.md— Main deliverable (Dunford 5 components)positioning-statement.md— Moore + Neumeier statements + elevator pitchcompetitive-alternatives.md— JTBD-informed alternatives mapmarket-category-analysis.md— Category candidates + recommendationmessaging-implications.md— Bridge from positioning to copyraw/— Raw research data from each wave
startup-pitch generates files in {project-name}/:
intake.md— Product, team, and pitch contextpitch-full.md— Full 10-minute pitch narrativepitch-5min.md— Compressed 5-minute versionpitch-2min.md— Verbal 2-minute pitch scriptpitch-1min.md— Elevator pitch (formal + casual)pitch-email.md— Investor cold email + follow-uppitch-appendix.md— Q&A preparation, objection handlingpitch-deck-outline.md— Slide-by-slide deck structure with headlines, visuals, speaker notespitch-scorecard.md— Pitch quality scoring rubricraw/— Raw research data from each wave
Integration Between Skills
startup-competitors can detect and leverage prior startup-design output. If files like 01-discovery/competitor-landscape.md exist, it uses them as a starting point instead of re-interviewing.
startup-positioning can detect and leverage output from BOTH startup-design (intake, discovery, strategy) and startup-competitors (battle cards, pricing landscape). It uses prior data as a head start and skips redundant intake questions.
startup-pitch can detect and leverage output from ALL three other skills. startup-design is the recommended prior work (provides market data, business model, validation scorecard). It also reads startup-competitors (battle cards for Q&A prep) and startup-positioning (positioning statements, messaging hierarchy).
Testing
Eval cases are in {skill}-workspace/evals/evals.json. To test:
- Run each eval prompt through the skill
- Grade against assertions in
eval_metadata.json - Compare with/without skill performance
Git Workflow
Commit Messages
Follow conventional commits:
feat: add new phase or capabilityfix: improve skill instructionsdocs: update README or CLAUDE.mdtest: add or update eval cases
Branch Naming
feature/descriptionfix/descriptiondocs/description