Skip to content

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

fix: sync AGENTS.md with CLAUDE.md content

Ferdinando Bonsegna33a928860a56
diff --git a/AGENTS.md b/AGENTS.md
index 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`