Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 0 additions & 25 deletions .claude-plugin/marketplace.json

This file was deleted.

2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug-report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,6 @@ body:
id: agent
attributes:
label: AI agent used
placeholder: "Claude Code, Cursor, etc."
placeholder: "Qwen Code、Ollama、Gemini CLI 等"
validations:
required: false
216 changes: 12 additions & 204 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,210 +1,18 @@
# AGENTS.md

Guidelines for AI agents working in this repository.
本仓库包含四个面向中国市场的通用 Agent Skills:`startup-design`、`startup-competitors`、`startup-positioning` 和 `startup-pitch`。

## 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).
- 技能目录名必须与 `SKILL.md` frontmatter 的 `name` 一致,使用小写英文和连字符。
- `description` 为 1—1024 个字符,包含清晰的中文触发场景;`SKILL.md` 不超过 500 行。
- 默认使用简体中文;中国市场数据必须注明来源、日期、地域、币种和统计口径。
- 阶段细节放入 `references/`,研究轮次文件使用 `research-wave-N-` 前缀并按需加载。
- 不绑定特定商业模型,不要求付费订阅或 API Key;优先兼容通用 Agent Skills、免费额度模型和 Ollama 本地模型。
- 搜索不可用时进入知识库模式,明确标记假设和待验证项,不伪造实时来源。
- 四个技能的研究轮次必须顺序执行;轮内是否并行由当前 Agent 环境决定。
- 修改后检查 YAML frontmatter、相对路径、文件行数和平台耦合词。

- **Name**: Startup Skills
- **GitHub**: [ferdinandobons/startup-skill](https://github.com/ferdinandobons/startup-skill)
- **Creator**: Ferdinando Bons
- **License**: MIT
## Git

## 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 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)

**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 interviews
- `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

**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

**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
- `messaging-implications.md` — Bridge from positioning to copy
- `raw/` — Raw research data from each wave

**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-deck-outline.md` — Slide-by-slide deck structure with headlines, visuals, speaker notes
- `pitch-scorecard.md` — Pitch quality scoring rubric
- `raw/` — 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:
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`
提交信息使用 Conventional Commits:`feat:`、`fix:`、`docs:` 或 `test:`。分支使用 `feature/`、`fix/` 或 `docs/` 前缀。
Loading