AGENTS.md — Startup Skills

Guidance for any agent (Claude Code, Codex, Cursor, Gemini CLI, …) or human working in this repo. This is the source of truth; CLAUDE.md carries the essentials and points here.

What this repo is

A public Agent Skills collection for founders building AI-native startups: one hub skill — founder-playbook — that diagnoses a founder's lifecycle stage and routes to 12 single-purpose per-function skills (validation, product, GTM, growth, fundraising, finance, sales, marketing, customer success, operations, legal). It's packaged for skills.sh and installed per-skill via npx skills add samuelcastro/startup-skills/<skill>. There is no build and no app — it's a set of portable skill folders.

IMPORTANT — load-bearing rules

The things you can't infer from the files, where getting it wrong has real consequences:

1. This collection is adapted, not original — attribution is non-negotiable.
   • The 12 per-function skills are adapted from Linas Beliūnas's The One-Person Unicorn founder skill set (https://linas.substack.com/p/onepersonunicorn).
   • founder-playbook is distilled from Anthropic's The Founder's Playbook: Building an AI-Native Startup.
   • Never reword the README or any skill to claim original authorship, and never delete a credit line. A skill adapted from someone else's work keeps its credit.
2. This repo is public — never leak private context. No references to private repos, internal knowledge bases/vaults, or machine-local absolute paths (/Users/...). Every skill must be fully self-contained and make sense to a stranger. Run the public-safety sweep below before committing.
3. Don't vendor third-party source text. Link to and credit a source; don't copy its full copyrighted text into this MIT repo.

Skill conventions (agentskills.io spec)

• One folder per skill, each with a required SKILL.md. Optional references/ (depth, loaded on demand), scripts/ (executable helpers), assets/.
• Frontmatter: name (MUST equal the folder name) and description (required). Optional metadata (author, version, license).
• The description is the trigger. It's the only thing an agent sees when deciding whether to invoke the skill — make it specific and a little "pushy": what the skill does AND the concrete situations/phrases that should fire it. Keep it ≤ ~1000 characters. Loaders reject descriptions over 1024 chars and silently skip the skill ("Skipped loading 1 skill"). This has bitten this collection before — stay under.
• Progressive disclosure. Keep SKILL.md lean (under ~500 lines). Push depth, templates, and long playbooks into references/ and point to them. Reference files over ~300 lines get a table of contents.
• Imperative, and explain the "why." Direct instructions that give the reasoning generalize better than rigid walls of ALWAYS/NEVER.

Adding a skill

1. Create <skill-name>/SKILL.md with name: <skill-name> (matching the folder) and a tight, trigger-oriented description.
2. Put depth in <skill-name>/references/.
3. Add a row to the README "Skills in this collection" table.
4. If it's adapted from someone's work, add a credit line.
5. Run the checks below.

Improving a skill (Karpathy autoresearch loop)

Skills drift — the same skill nails the output ~70% of the time and rambles the rest. The fix is the autoresearch eval loop (Karpathy's method, applied to SKILL.md):

• Define a number. Run the skill ~30× across 3–5 real test prompts; score each output against 3–6 binary yes/no criteria; the metric is pass rate.
• Write evals that resist gaming. Binary only (no 1–7 scales). Observable, not subjective ("includes a specific next step with a named tool/timeline," not "is it actionable"). Gaming-resistant ("a metric derived from the user's inputs," not "contains a number"). Cover both presence (frameworks, concrete steps) and absence (generic filler, buzzwords).
• One file changes per round — only the SKILL.md. The evals and test inputs are locked; editing them mid-run optimizes the test instead of the skill. Keep the change if pass rate improves by ≥10 points, else revert.

(If you have the skill-creator skill, it automates a version of this loop.)

Validate before committing

# Public-safety: no machine-local paths leaked into a public repo
grep -rn '/Users/' . --include='*.md'                 # expect: no matches

# Spec: each skill's `name` must equal its folder, and each `description` ≤ 1024 chars.
# Validate with the agentskills.io reference tool:
npx skills-ref validate ./<skill-name>

License

MIT (see LICENSE). The underlying frameworks belong to their authors (Linas Beliūnas; Anthropic); the MIT license covers this packaging, not the source frameworks.