2026-04-20 19:32:42 +00:00
4 changed files with 107 additions and 87 deletions
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ The design system provides three things for AI agents:
 | File | What it is | Where it goes |
 |------|-----------|---------------|
 | **SKILL.md** | Full design system reference (tokens, all components, composition rules, extension protocol) | `.claude/skills/` — works in Claude Code, Cursor, OpenCode, Anigravity, etc. |
-| **AGENT.md** | Short project instructions telling the AI *how* to use the design system (like CLAUDE.md but portable) | Project root — copy as `AGENT.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md` |
+| **AGENTS.md** | Short project instructions telling the AI *how* to use the design system (follows the [agents.md](https://agents.md) convention) | Project root — copy as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md` |
 | **MCP Server** | Runtime tools for looking up components, validating colors, suggesting components | Configured in `.mcp.json` |

 All are auto-generated from the same sources (`tokens/*.json` and `lib/catalog.ts`).
@@ -71,11 +71,14 @@ All are auto-generated from the same sources (`tokens/*.json` and `lib/catalog.t
 ./skill/install.sh /path/to/your/project
 ```

-This will:
-1. Symlink `SKILL.md` into `.claude/skills/` (full reference for any AI agent)
-2. Copy `AGENT.md` into the project root (project-level instructions)
-3. Copy Aspekta font files into `public/fonts/`
-4. Print CSS import instructions
+This **copies** (not symlinks) the following into your project:
+1. `SKILL.md` → `.claude/skills/greyhaven-design-system.md` (full reference)
+2. `AGENTS.md` → project root (project-level instructions)
+3. Aspekta font files → `public/fonts/`
+
+The script also prints the CSS `@font-face` block and MCP server config to add next.
+
+**Re-run the script after design system updates** to refresh your copies.

 ### SKILL.md (full reference)

@@ -84,43 +87,37 @@ The skill file gives any AI agent full design system context — every token, ev
 **It's a global standard** — works with Claude Code, Cursor, OpenCode, Anigravity, and any tool that reads skill files.

 ```bash
-# Via install script
+# Via install script (recommended — also handles fonts + AGENTS.md)
 ./skill/install.sh /path/to/your/project

-# Or manually
+# Or copy manually
 mkdir -p /path/to/your/project/.claude/skills
-ln -sf /absolute/path/to/greyhaven-design-system/skill/SKILL.md \
-       /path/to/your/project/.claude/skills/greyhaven-design-system.md
+cp /path/to/greyhaven-design-system/skill/SKILL.md \
+   /path/to/your/project/.claude/skills/greyhaven-design-system.md
 ```

-### AGENT.md (project instructions)
+### AGENTS.md (project instructions)

-Short, directive instructions that tell the AI agent *how* to work in the project — use TypeScript, use semantic tokens, reference the MCP tools, etc. This is the equivalent of `CLAUDE.md` but portable across tools.
+Short, directive instructions that tell the AI agent *how* to work in the project — use TypeScript, use semantic tokens, reference the MCP tools, etc. Follows the [agents.md](https://agents.md) convention so it works with most AI coding tools out of the box.

 **Copy it to your project root** under whichever name your tool reads:

 ```bash
-# Claude Code
-cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/CLAUDE.md
+# Standard (agents.md convention — Cursor, OpenCode, Windsurf, Aider, etc.)
+cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/AGENTS.md

-# Cursor
-cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/.cursorrules
+# Claude Code
+cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/CLAUDE.md
+
+# Cursor (legacy)
+cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/.cursorrules

 # GitHub Copilot
 mkdir -p /path/to/your/project/.github
-cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/.github/copilot-instructions.md
-
-# Or just use the install script which symlinks AGENT.md to the root
-./skill/install.sh /path/to/your/project
-
-# Or manually
-ln -sf /absolute/path/to/greyhaven-design-system/skill/AGENT.md \
-       /path/to/your/project/AGENT.md
+cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/.github/copilot-instructions.md
 ```

-Some tools use different file names. You can also symlink as:
- `.cursorrules` (Cursor)
- `.github/copilot-instructions.md` (GitHub Copilot)
+Or use the install script, which copies `AGENTS.md` to the project root automatically.

 ### Option C: MCP Server

--- a/scripts/generate-skill.ts
+++ b/scripts/generate-skill.ts
@@ -1,15 +1,15 @@
 #!/usr/bin/env npx tsx

 /**
- * Generates skill/SKILL.md and skill/AGENT.md from the shared component
+ * Generates skill/SKILL.md and skill/AGENTS.md from the shared component
 * catalog and W3C DTCG token files. Run via `pnpm skill:build`.
 *
 * Both the MCP server and this script read from lib/catalog.ts and
 * tokens/*.json, so all outputs stay in sync.
 *
 * Outputs:
- *   skill/SKILL.md  — Claude Code skill (loaded via .claude/skills/)
- *   skill/AGENT.md  — Generic AI agent instructions (Cursor, Copilot, etc.)
+ *   skill/SKILL.md   — Full design system reference (tokens, components, rules)
+ *   skill/AGENTS.md  — Project-level instructions for any AI coding agent
 */

 import * as fs from 'fs'
@@ -45,7 +45,7 @@ function componentCount(): number {
 }

 // ---------------------------------------------------------------------------
-// Shared content blocks (used by both SKILL.md and AGENT.md)
+// Shared content blocks (used by both SKILL.md and AGENTS.md)
 // ---------------------------------------------------------------------------

 function buildDesignPhilosophy(): string {
@@ -261,7 +261,7 @@ This skill gives you full context to generate pixel-perfect, on-brand UI using t
 }

 // ---------------------------------------------------------------------------
-// AGENT.md (project-level instructions for non-Claude AI agents)
+// AGENTS.md (project-level instructions for non-Claude AI agents)
 // ---------------------------------------------------------------------------

 function generateAgent(): string {
@@ -279,8 +279,8 @@ function generateAgent(): string {
 > **Auto-generated** by the Greyhaven Design System.
 > Re-generate: \`pnpm skill:build\` in the design system repo.
 >
-> Copy this file to your project root as \`AGENT.md\`, \`.cursorrules\`,
-> or \`.github/copilot-instructions.md\` depending on your AI tool.
+> Copy this file to your project root as \`AGENTS.md\` (standard), \`CLAUDE.md\`,
+> \`.cursorrules\`, or \`.github/copilot-instructions.md\` depending on your AI tool.

 This project uses the **Greyhaven Design System**.

@@ -345,12 +345,12 @@ function main() {
  const skillLines = skill.split('\n').length
  console.log(`skill/SKILL.md generated (${skillLines} lines, ${componentCount()} components)`)

-  // AGENT.md
+  // AGENTS.md
  const agent = generateAgent()
-  const agentPath = path.join(outDir, 'AGENT.md')
+  const agentPath = path.join(outDir, 'AGENTS.md')
  fs.writeFileSync(agentPath, agent, 'utf-8')
  const agentLines = agent.split('\n').length
-  console.log(`skill/AGENT.md generated (${agentLines} lines, ${componentCount()} components)`)
+  console.log(`skill/AGENTS.md generated (${agentLines} lines, ${componentCount()} components)`)
 }

 main()
--- a/skill/AGENTS.md
+++ b/skill/AGENTS.md
@@ -3,8 +3,8 @@
 > **Auto-generated** by the Greyhaven Design System.
 > Re-generate: `pnpm skill:build` in the design system repo.
 >
-> Copy this file to your project root as `AGENT.md`, `.cursorrules`,
-> or `.github/copilot-instructions.md` depending on your AI tool.
+> Copy this file to your project root as `AGENTS.md` (standard), `CLAUDE.md`,
+> `.cursorrules`, or `.github/copilot-instructions.md` depending on your AI tool.

 This project uses the **Greyhaven Design System**.

--- a/skill/install.sh
+++ b/skill/install.sh
@@ -1,11 +1,14 @@
 #!/usr/bin/env bash
 # install.sh — Install the Greyhaven Design System into a consuming project.
 #
+# Copies (does NOT symlink) files so the consuming project owns its copies.
+# Re-run this script to pull updated versions after design system changes.
+#
 # What it does:
-#   1. Symlinks SKILL.md into .claude/skills/ (for Claude Code)
-#   2. Symlinks AGENT.md into the project root (for non-Claude AI agents)
-#   3. Copies Aspekta font files + @font-face CSS into public/fonts/
-#   4. Prints CSS import instructions for the consuming project
+#   1. Copies SKILL.md into .claude/skills/ (for Claude Code)
+#   2. Copies AGENTS.md into the project root (standard convention)
+#   3. Copies Aspekta font files + font-face.css into public/fonts/
+#   4. Prints CSS import + MCP setup instructions
 #
 # Usage:
 #   ./skill/install.sh /path/to/your/project
@@ -15,7 +18,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 SKILL_FILE="${SCRIPT_DIR}/SKILL.md"
-AGENT_FILE="${SCRIPT_DIR}/AGENT.md"
+AGENTS_FILE="${SCRIPT_DIR}/AGENTS.md"
 FONTS_DIR="${REPO_ROOT}/public/fonts"

 if [ $# -ge 1 ]; then
@@ -34,41 +37,43 @@ if [ ! -d "$TARGET_PROJECT" ]; then
  exit 1
 fi

+# Helper: backup existing file/symlink and copy new one
+copy_with_backup() {
+  local src="$1"
+  local dst="$2"
+
+  if [ -L "$dst" ]; then
+    # Remove any existing symlink (leftover from old installs)
+    rm "$dst"
+  elif [ -f "$dst" ]; then
+    mv "$dst" "${dst}.bak"
+    echo "      (backed up existing file to $(basename "${dst}.bak"))"
+  fi
+
+  cp "$src" "$dst"
+}
+
 echo "Installing Greyhaven Design System into ${TARGET_PROJECT}"
 echo ""

-# ── 1. Claude Skill ────────────────────────────────────────────────────────
+# ── 1. SKILL.md ────────────────────────────────────────────────────────────
 if [ -f "$SKILL_FILE" ]; then
  SKILLS_DIR="${TARGET_PROJECT}/.claude/skills"
  mkdir -p "$SKILLS_DIR"
-  LINK_PATH="${SKILLS_DIR}/greyhaven-design-system.md"
-
-  if [ -L "$LINK_PATH" ]; then
-    rm "$LINK_PATH"
-  elif [ -f "$LINK_PATH" ]; then
-    mv "$LINK_PATH" "${LINK_PATH}.bak"
-  fi
-
-  ln -s "$SKILL_FILE" "$LINK_PATH"
-  echo "[ok] Claude Skill:  ${LINK_PATH} -> ${SKILL_FILE}"
+  DST="${SKILLS_DIR}/greyhaven-design-system.md"
+  copy_with_backup "$SKILL_FILE" "$DST"
+  echo "[ok] SKILL.md:      ${DST}"
 else
  echo "[skip] SKILL.md not found — run 'pnpm skill:build' first"
 fi

-# ── 2. AGENT.md ────────────────────────────────────────────────────────────
-if [ -f "$AGENT_FILE" ]; then
-  AGENT_LINK="${TARGET_PROJECT}/AGENT.md"
-
-  if [ -L "$AGENT_LINK" ]; then
-    rm "$AGENT_LINK"
-  elif [ -f "$AGENT_LINK" ]; then
-    mv "$AGENT_LINK" "${AGENT_LINK}.bak"
-  fi
-
-  ln -s "$AGENT_FILE" "$AGENT_LINK"
-  echo "[ok] AGENT.md:      ${AGENT_LINK} -> ${AGENT_FILE}"
+# ── 2. AGENTS.md ───────────────────────────────────────────────────────────
+if [ -f "$AGENTS_FILE" ]; then
+  DST="${TARGET_PROJECT}/AGENTS.md"
+  copy_with_backup "$AGENTS_FILE" "$DST"
+  echo "[ok] AGENTS.md:     ${DST}"
 else
-  echo "[skip] AGENT.md not found — run 'pnpm skill:build' first"
+  echo "[skip] AGENTS.md not found — run 'pnpm skill:build' first"
 fi

 # ── 3. Fonts ───────────────────────────────────────────────────────────────
@@ -76,16 +81,15 @@ if [ -d "$FONTS_DIR" ]; then
  TARGET_FONTS="${TARGET_PROJECT}/public/fonts"
  mkdir -p "$TARGET_FONTS"

-  # Copy only Aspekta woff2 files and the font-face CSS
  copied=0
  for f in "$FONTS_DIR"/Aspekta-*.woff2; do
    [ -f "$f" ] || continue
-    cp -n "$f" "$TARGET_FONTS/" 2>/dev/null && copied=$((copied + 1)) || true
+    cp "$f" "$TARGET_FONTS/"
+    copied=$((copied + 1))
  done

-  # Copy font-face.css
  if [ -f "$FONTS_DIR/font-face.css" ]; then
-    cp -n "$FONTS_DIR/font-face.css" "$TARGET_FONTS/" 2>/dev/null || true
+    cp "$FONTS_DIR/font-face.css" "$TARGET_FONTS/"
  fi

  echo "[ok] Fonts:         ${copied} Aspekta woff2 files copied to ${TARGET_FONTS}/"
@@ -93,18 +97,37 @@ else
  echo "[skip] Fonts dir not found at ${FONTS_DIR}"
 fi

-# ── Done ───────────────────────────────────────────────────────────────────
-echo ""
-echo "Done! Next steps for your project's CSS entry point:"
-echo ""
-echo "  /* Add these @font-face declarations to your global CSS */"
-echo "  @font-face { font-family: 'Aspekta'; font-weight: 400; font-display: swap; src: url('/fonts/Aspekta-400.woff2') format('woff2'); }"
-echo "  @font-face { font-family: 'Aspekta'; font-weight: 500; font-display: swap; src: url('/fonts/Aspekta-500.woff2') format('woff2'); }"
-echo "  @font-face { font-family: 'Aspekta'; font-weight: 600; font-display: swap; src: url('/fonts/Aspekta-600.woff2') format('woff2'); }"
-echo "  @font-face { font-family: 'Aspekta'; font-weight: 700; font-display: swap; src: url('/fonts/Aspekta-700.woff2') format('woff2'); }"
-echo ""
-echo "  /* Or import the full set: */"
-echo "  @import url('/fonts/font-face.css');"
-echo ""
-echo "  /* Set your font stack: */"
-echo "  --font-sans: 'Aspekta', ui-sans-serif, system-ui, sans-serif;"
+# ── Next steps ─────────────────────────────────────────────────────────────
+cat <<'EOF'
+
+Done!
+
+─── Next steps ────────────────────────────────────────────────────────────
+
+1. Add Aspekta @font-face to your global CSS:
+
+   @font-face { font-family: 'Aspekta'; font-weight: 400; font-display: swap; src: url('/fonts/Aspekta-400.woff2') format('woff2'); }
+   @font-face { font-family: 'Aspekta'; font-weight: 500; font-display: swap; src: url('/fonts/Aspekta-500.woff2') format('woff2'); }
+   @font-face { font-family: 'Aspekta'; font-weight: 600; font-display: swap; src: url('/fonts/Aspekta-600.woff2') format('woff2'); }
+   @font-face { font-family: 'Aspekta'; font-weight: 700; font-display: swap; src: url('/fonts/Aspekta-700.woff2') format('woff2'); }
+
+   (Or import the full set: @import url('/fonts/font-face.css');)
+
+   And set the font stack:
+   --font-sans: 'Aspekta', ui-sans-serif, system-ui, sans-serif;
+
+2. (Optional) Register the Greyhaven MCP server. Create .mcp.json in your
+   project root:
+
+   {
+     "mcpServers": {
+       "greyhaven": {
+         "command": "npx",
+         "args": ["tsx", "<ABSOLUTE_PATH_TO_GREYHAVEN_REPO>/mcp/server.ts"]
+       }
+     }
+   }
+
+3. Re-run this script after design system updates to refresh your copies.
+
+EOF