Add SKILL.md so this repo installs as a Claude Code skill
Points an agent at the real files rather than restating them: README.md and rationale.md for voice/foundations/rules, _components/<name>.md for each component's exact markup contract (no class API — bare elements, ARIA roles, data-* attributes, and exactly seven sanctioned single classes), install.md for embedding and retheming. Also flags that vendoring this site's own deployed style.css would drag in _sass/site/*.css (this documentation site's chrome) along with the actual reusable system — the skill instead says to concatenate just base/ + components/, and I verified that produces a clean 933-line file with zero .ad-doc-*/.example leakage. Fixed a few stale path references in install.md left over from the lib/build.rb rewrite (lib/arbitrary_definitions/site_builder.rb, _includes/) and a leftover type="button" in its illustrative example snippet.
diff --git a/README.md b/README.md
index 628c138..76df3da 100644
--- a/README.md
+++ b/README.md
@@ -94,3 +94,17 @@ Two files, in this order, and almost no JavaScript:
Retheming means overriding a handful of custom properties after `tokens.css`
loads — no recompile, no fork. See [Using the CSS](https://kejadlen.github.io/arbitrary-definitions-design-system/install/).
+
+## Claude Code skill
+
+This repo doubles as a Claude Code skill — `SKILL.md` at the root, in the
+standard [Agent Skills](https://code.claude.com/docs/en/skills) format.
+Clone this repo into `.claude/skills/arbitrary-definitions/` in another
+project and Claude picks it up automatically, with the exact component
+contracts, tokens, and voice guidance to build new interfaces that look like
+they came from the same hand as this one:
+
+```console
+$ git clone https://github.com/kejadlen/arbitrary-definitions-design-system \
+ .claude/skills/arbitrary-definitions
+```
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..1a49a20
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: arbitrary-definitions
+description: Use this skill to build interfaces, pages, or prototypes in the Arbitrary Definitions style — a personal design system for self-hosted, single-user tools. Warm low-chroma neutrals, one swappable accent, IBM Plex Mono labels, and sixteen components built as plain HTML with no CSS class API to memorize. Use whenever a project should look like it came from the same hand as the others in this umbrella.
+user-invocable: true
+---
+
+Read `README.md` and `rationale.md` in this repo before building anything —
+they cover the voice, the visual foundations, and the four hard rules (no
+hex or duration outside `tokens.css`, components read aliases not ramps,
+every token says what it's for, one accent per project, never two in a
+view). `install.md` covers embedding and retheming in more depth than this
+file repeats.
+
+## Getting the CSS into another project
+
+Two files, in this order, no build step:
+
+```html
+<link rel="stylesheet" href="tokens.css">
+<link rel="stylesheet" href="style.css">
+```
+
+`tokens.css` is already exactly that file:
+[`assets/css/tokens.css`](assets/css/tokens.css). `style.css` is **not**
+this site's deployed `style.css` — that also bundles this documentation
+site's own chrome (`_sass/site/*.css`: the sidebar, the example-demo boxes,
+doc tables), which has nothing to do with the design system itself. Build
+the real one from just base + components:
+
+```console
+$ cat _sass/base/reset.css _sass/base/typography.css _sass/components/*.css > style.css
+```
+
+Load IBM Plex Mono separately — the system's one webfont:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&display=swap');
+```
+
+## Writing markup
+
+There is no class API to memorize. Every component has its exact contract
+documented in `_components/<name>.md` — **read the specific file for the
+component you're about to use before writing its markup**, rather than
+guessing from a similar one or from memory:
+
+- Bare elements styled directly: `<button>`, `<input>`, `<select>`, native
+ `<dialog>` (with `<header>`/`<footer>` and `::backdrop` — no wrapper
+ divs).
+- ARIA roles doing double duty as style hooks: `[role="tablist"]`,
+ `[role="tab"]`, `[role="tabpanel"]`, `[role="status"]`, `[role="tooltip"]`,
+ `[role="switch"]` — these are the correct accessibility attributes
+ regardless, so using them as selectors invents nothing.
+- `data-*` attributes for variants and states: `data-variant="primary"`,
+ `data-size="sm"`, `data-tone="danger"`, `data-elevated`.
+- Exactly seven plain, unmodified classes exist, each because there is no
+ element or attribute to hang a selector on: `.btn` (an `<a>` acting as a
+ button — a bare `a` selector would catch every prose link on the page),
+ `.icon-button`, `.badge`, `.tag`, `.card`, `.field`, `.switch` (fallback
+ only, for the track/thumb). Never invent an eighth, and never add a `--`
+ or `__` modifier to one of these — that convention was deliberately
+ removed from this system.
+
+## Voice
+
+Plain, unhurried, never marketing copy. These are tools for one person or
+one household — copy never addresses "you" as a customer, and empty states
+just state the fact ("Nothing tracked yet."). See README's "The idea" and
+`rationale.md`'s "Where the name comes from" for the fuller version.
+
+## Retheming
+
+One accent per project, held constant — swap `--ad-color-accent` after
+`tokens.css` loads; `-ink` and `-soft` re-derive automatically via
+`color-mix()`. `--ad-color-success` and `--ad-color-danger` are fixed and
+never swapped. Re-check contrast after retheming — the system's own
+guarantees (see the [Color foundation](foundations/color.md)) are about its
+own values, not yours.
diff --git a/install.md b/install.md
index b7046b0..290a1ce 100644
--- a/install.md
+++ b/install.md
@@ -85,10 +85,10 @@ a handful of custom properties after the token file loads — most of all,
## Building this site
There is no Jekyll here — the whole site is a Rakefile driving plain ERB
-templates and Kramdown (see `lib/arbitrary_definitions/site_builder.rb`). It
-still builds on GitHub Actions and uploads the result to Pages, mainly so the
-build always runs on the pinned Ruby 4.0 rather than whatever GitHub's Pages
-runner happens to ship. Locally:
+templates and Kramdown (see `lib/build.rb`). It still builds on GitHub
+Actions and uploads the result to Pages, mainly so the build always runs on
+the pinned Ruby 4.0 rather than whatever GitHub's Pages runner happens to
+ship. Locally:
```console
$ rbenv install 4.0.6 # or however you get Ruby 4.0
@@ -104,8 +104,8 @@ $ bundle exec rake serve # http://127.0.0.1:4000
<tbody>
<tr><td><code>assets/css/tokens.css</code></td><td>Every value in the system, hand-maintained.</td></tr>
<tr><td><code>_sass/</code></td><td>One plain CSS file per component group, concatenated into <code>style.css</code> at build time. No hexes, no pixels, no durations.</td></tr>
- <tr><td><code>lib/arbitrary_definitions/</code></td><td>The whole site builder — front matter, ERB, and Kramdown, wrapped in a layout.</td></tr>
- <tr><td><code>_layouts/, _includes/</code></td><td>Plain ERB templates for the page chrome.</td></tr>
+ <tr><td><code>lib/build.rb</code></td><td>The whole site builder in one file — a literal list of pages, front matter, ERB, and Kramdown.</td></tr>
+ <tr><td><code>_layouts/page.erb</code></td><td>The one page shell (head, header, sidebar, footer).</td></tr>
<tr><td><code>_components/, _foundations/, _patterns/</code></td><td>Static Markdown and HTML — the content itself, hand-written.</td></tr>
</tbody>
</table>
@@ -122,12 +122,12 @@ the page is how the source panel gets written, so there is nothing to drift.
<figure class="example">
<figcaption>Variants</figcaption>
<div>
- <button type="button">Cancel</button>
- <button type="button" data-variant="primary">Save</button>
+ <button>Cancel</button>
+ <button data-variant="primary">Save</button>
</div>
<details><summary>Markup</summary>
-<pre><code><button type="button">Cancel</button>
-<button type="button" data-variant="primary">Save</button></code></pre>
+<pre><code><button>Cancel</button>
+<button data-variant="primary">Save</button></code></pre>
</details>
</figure>
```