# Contributing to OpenDesign

Thanks for considering a contribution. OpenDesign is an open-source, skills-based version of [Claude Design](https://claude.ai/design) — the goal is parity with that experience, not feature creep. This repo ships a small, opinionated set of skills; quality bar is higher than coverage. Before adding a new skill, strongly consider whether an existing one can be extended instead.

## Ground rules

- Every `SKILL.md` is written in direct imperative voice. No marketing language, no apologies, no emoji, no "as we discussed".
- Concrete beats vague. Specific rules, forbidden patterns, and measured constants beat aspirational prose.
- Skills describe *behavior under specific conditions*, not philosophies. If your skill body is abstract, it's not ready.

## SKILL.md format

```markdown
---
name: your-skill-name
description: Use when [specific triggering conditions]. [One-line summary of what it produces.]
---

Loaded when [restate trigger].

## [Section]

[Rules, constants, forbidden patterns, required paths. Be concrete.]
```

Rules:

- `name` uses lowercase and hyphens. Must match the folder name.
- `description` starts with "Use when..." and describes *when the skill applies*, not what it does internally. The agent reads this to decide whether to load the skill.
- Do not summarize the skill's workflow in the description — the skill body is authoritative.

## Adding a new skill

1. Create `skills/<name>/SKILL.md` with frontmatter and body.
2. Add a row to the "Available skills" table in `README.md`.
3. Open a PR. In the description, state:
   - What the skill does.
   - Why existing skills can't cover this case.
   - Any risk of overlap with `opendesign`, `frontend-design`, `create-design-system`, or `make-a-deck`.

## Editing an existing skill

- Keep the frontmatter `name` stable — changing it is a breaking change for users.
- If you're narrowing or widening the trigger, update the `description` in the same change.
- Bump the version in every host config for any user-visible change. Run `bash validate-skills.sh` to catch version drift.

## Things I'll reject

- Skills that replicate what an existing skill covers with minor variation.
- Skill bodies that read like a blog post or pitch.
- Emoji, marketing adjectives, or aspirational prose.
- Frontmatter that summarizes the skill's workflow instead of its trigger.
- PRs that add a skill file but forget the README update.