# Commons — Design Skills for Coding Agents

Commons is a registry of human-curated design skills. Each design skill is a full
design philosophy (colors, typography, spacing, component patterns) that you can
apply to make the app you're building look distinctive instead of generic.

## Quick start

1. Browse available design skills:

   GET https://joincommons.cc/api/items?sort=trending&limit=10

2. Search by keyword or domain:

   GET https://joincommons.cc/api/items?q=dashboard

3. Pick a design skill. Each item includes:
   - title, description         — what it is
   - bestFor, avoidFor           — product fit
   - coaching.identity           — one-sentence design philosophy
   - coaching.signatureMoves     — key visual decisions
   - curationTier                — benchmark (best), catalog, or archive
   - cardThumbnailUrl            — visual preview

   Shortlist 2-3. Compare coaching fields. Pick one.

4. Get full detail for the chosen skill:

   GET https://joincommons.cc/api/items/{slug}

5. Read the SKILL.md at the returned designSkillUrl. This is your apply
   entry point — it tells you what to do and routes you to DESIGN.md,
   design tokens, and supporting files as needed.

6. After applying, record it:

   POST https://joincommons.cc/api/items/{slug}/apply

## Staged loading (save context window)

- Discovery: use the list endpoint. Read metadata only.
- Selection: compare coaching fields across 2-3 candidates.
- Apply: fetch designSkillUrl first, then follow its references
  to designLanguageUrl and tokensDtcgUrl.

Do NOT load DESIGN.md until after you've picked a skill.

## API reference

GET  /api/items                     — list all (supports ?q=, ?sort=, ?limit=)
GET  /api/items/{slug}              — full detail + artifact URLs
POST /api/items/{slug}/apply        — record that you applied this skill

## Key fields in item detail response

designSkillUrl       — SKILL.md (agent instructions, your entry point)
designLanguageUrl    — DESIGN.md (full design language spec)
tokensDtcgUrl        — Design tokens in DTCG format
cardThumbnailUrl     — Card preview image
coaching.identity    — One-sentence design philosophy
coaching.signatureMoves — Array of key visual decisions
coaching.hardConstraints — Array of must-follow rules

## Optional: MCP server

For richer tool integration, install the Commons MCP server:

  npx commons-mcp@latest

Provides tools: list_design_skills, search_design_skills,
get_design_skill, get_design_language, recommend_design_skills.