AI agent skills for startup validation, competitive intelligence, and planning
AGENTS.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
├── AGENTS.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 use dynamic research scaling. After intake, a complexity score (3-9) is calculated from market breadth, known competitors, and geographic scope. This maps to three tiers:
- Light (3-4): Merged agents, 2-3 search rounds. Quick scan for niche markets.
- Standard (5-7): Default behavior, unchanged from current wave structure.
- Deep (8-9): Extra agents per wave, 5-6 search rounds. Thorough due diligence.
Users can override with "light", "deep", or "ok". See each skill's references/research-scaling.md for wave configurations per tier.
Verification Agent
All skills run a V1: Verification agent after synthesis. It audits deliverables for: unlabeled claims, internal contradictions, confidence rating consistency, missing data gaps, missing flags, stale data, and duplicate-source false corroboration. Each skill adds domain-specific checks (e.g., cross-phase consistency for startup-design, battle card coherence for startup-competitors). Output: verification-report.md. Critical issues pause the flow 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