AI agent skills for startup validation, competitive intelligence, and planning
ai-agentsbattle-cardsclaude-codeclaude-skillscompetitive-analysiscompetitive-intelligencemarket-researchpricing-analysisstartupstartup-validation
fix: sync AGENTS.md with CLAUDE.md content
Ferdinando Bonsegna33a928860a56
diff --git a/AGENTS.md b/AGENTS.mdindex 77a1304..c74c6f8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -4,76 +4,177 @@ 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.+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 Design Skill+- **Name**: Startup Skills- **GitHub**: [ferdinandobons/startup-skill](https://github.com/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/-├── 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+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 (~522 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+├── startup-competitors/ # Skill: startup:startup-competitors+│ ├── SKILL.md # Main skill file (~220 lines, 3 waves)+│ └── references/+│ ├── research-principles.md+│ ├── research-wave-1-profiles-pricing.md+│ ├── research-wave-2-sentiment-mining.md+│ ├── research-wave-3-gtm-signals.md+│ ├── research-synthesis.md+│ └── honesty-protocol.md+├── startup-positioning/ # Skill: startup:startup-positioning+│ ├── SKILL.md # Main skill file (~240 lines, 2 waves)+│ └── references/+│ ├── research-principles.md+│ ├── research-wave-1-alternatives.md+│ ├── research-wave-2-market-frame.md+│ ├── research-synthesis.md+│ ├── frameworks.md+│ └── honesty-protocol.md+├── startup-pitch/ # Skill: startup:startup-pitch+│ ├── SKILL.md # Main skill file (~370 lines, 2 waves)+│ └── references/+│ ├── research-principles.md+│ ├── research-wave-1-audience-narrative.md+│ ├── research-wave-2-competitive-framing.md+│ ├── research-synthesis.md+│ ├── pitch-frameworks.md+│ └── honesty-protocol.md├── CLAUDE.md+├── AGENTS.md├── CONTRIBUTING.md├── LICENSE└── README.md```-## Skill Specification+## Key Conventions-The skill follows standard SKILL.md format with YAML frontmatter:+### Naming Convention-```yaml-----name: startup-design-description: Design, validate, and plan a startup from scratch...-----```+- **Plugin name** (`startup`): defined in `.claude-plugin/marketplace.json` → becomes the namespace prefix+- **Skill name** (`startup-design`, `startup-competitors`): defined in `SKILL.md` frontmatter → 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.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)+- 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)-### Frontmatter Constraints+**startup-pitch** uses 2 sequential waves of parallel agents:+- Wave 1: Audience & Narrative Intelligence (2 agents)+- Wave 2: Competitive Framing & Why Now (2 agents)-| 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. |+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.-### Progressive Loading+### Output Structure-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+**startup-design** 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-## Writing Style+**startup-competitors** generates files in `{project-name}/`:+- `intake.md` — Product and market context+- `competitors-report.md` — Main deliverable with strategic analysis+- `competitive-matrix.md` — Feature comparison table+- `pricing-landscape.md` — Pricing analysis and positioning+- `battle-cards/{competitor}.md` — Per-competitor one-pagers+- `raw/` — Raw research data from each wave-- 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+**startup-positioning** generates files in `{project-name}/`:+- `intake.md` — Product and market context+- `positioning-doc.md` — Main deliverable (Dunford 5 components)+- `positioning-statement.md` — Moore + Neumeier statements + elevator pitch+- `competitive-alternatives.md` — JTBD-informed alternatives map+- `market-category-analysis.md` — Category candidates + recommendation+- `raw/` — Raw research data from each wave-## Testing+**startup-pitch** generates files in `{project-name}/`:+- `intake.md` — Product, team, and pitch context+- `pitch-full.md` — Full 10-minute pitch narrative+- `pitch-5min.md` — Compressed 5-minute version+- `pitch-2min.md` — Verbal 2-minute pitch script+- `pitch-1min.md` — Elevator pitch (formal + casual)+- `pitch-email.md` — Investor cold email + follow-up+- `pitch-appendix.md` — Q&A preparation, objection handling+- `pitch-scorecard.md` — Pitch quality scoring rubric+- `raw/` — Raw research data from each wave-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+### 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:+1. Run each eval prompt through the skill+2. Grade against assertions in `eval_metadata.json`+3. Compare with/without skill performance## Git Workflow-- Branch naming: `feature/`, `fix/`, `docs/`-- Commit messages: conventional commits (`feat:`, `fix:`, `docs:`, `test:`)-- Always create new commits, never amend+### 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`