feat(mcp): add agent skills for component building and token discovery

.changeset/agent-skills-enhancements.md

@@ -0,0 +1,5 @@
+---
+"@adobe/spectrum-design-data-mcp": patch
+---
+
+Improved Agent Skills with better folder naming (agent-skills/), comprehensive documentation including quick start examples, state management guide, accessibility checklist, and enhanced error messages with actionable next steps.

.changeset/agent-skills-feature.md

@@ -0,0 +1,8 @@
+---
+"@adobe/spectrum-design-data-mcp": minor
+---
+
+Added Agent Skills for component building and token discovery.
+Agent Skills are markdown guides that help AI agents orchestrate
+MCP tools into complete workflows. Includes Component Builder and
+Token Finder skills, plus new workflow-oriented MCP tools.

.cursor/mcp.json

@@ -1,28 +1,10 @@
 {
   "mcpServers": {
-    "changesets Docs": {
-      "url": "https://gitmcp.io/changesets/changesets"
-    },
-    "ava Docs": {
-      "url": "https://gitmcp.io/avajs/ava"
-    },
     "moon": {
       "command": "moon",
       "args": ["mcp"],
       "cwd": "${workspaceFolder}"
     },
-    "handlebars.js Docs": {
-      "url": "https://gitmcp.io/handlebars-lang/handlebars.js"
-    },
-    "pnpm Docs": {
-      "url": "https://gitmcp.io/pnpm/pnpm"
-    },
-    "commitlint Docs": {
-      "url": "https://gitmcp.io/conventional-changelog/commitlint"
-    },
-    "GitHub cli Docs": {
-      "url": "https://gitmcp.io/cli/cli"
-    },
     "nixt Docs": {
       "url": "https://gitmcp.io/vesln/nixt"
     }

.github/workflows/publish-packages.yml

@@ -0,0 +1,77 @@
+name: Publish Packages (Reusable)
+
+on:
+  workflow_call:
+    inputs:
+      snapshot-tag:
+        description: "Optional snapshot tag for prerelease versions"
+        required: false
+        type: string
+    secrets:
+      GH_TOKEN:
+        required: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write # Required for npm trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get last author info
+        id: author
+        run: |
+          echo "authorName=$(git log -1 --pretty=format:'%an')" >> $GITHUB_OUTPUT
+          echo "authorEmail=$(git log -1 --pretty=format:'%ae')" >> $GITHUB_OUTPUT
+
+      - uses: moonrepo/setup-toolchain@v0
+        with:
+          auto-install: true
+
+      - run: moon setup
+      - run: moon run :build --query "projectSource~packages/*"
+
+      # Validate OIDC prerequisites before publishing
+      - name: Validate Publishing Prerequisites
+        uses: GarthDB/changesets-publish-validator@v1
+        with:
+          auth-method: oidc
+
+      # Install npm CLI with OIDC support for snapshot releases
+      - name: Install npm with OIDC support
+        if: inputs.snapshot-tag != ''
+        run: npm install -g npm@11.6.2
+
+      # Snapshot release
+      - name: Snapshot release
+        if: inputs.snapshot-tag != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          SNAPSHOT_TAG: ${{ inputs.snapshot-tag }}
+          USERNAME: ${{ steps.author.outputs.authorName }}
+          EMAIL: ${{ steps.author.outputs.authorEmail }}
+        run: |
+          pnpm changeset version --snapshot $SNAPSHOT_TAG
+          git config --global user.name "$USERNAME"
+          git config --global user.email "$EMAIL"
+          git add .
+          git commit -m "chore: snapshot release $SNAPSHOT_TAG"
+          pnpm changeset publish --tag $SNAPSHOT_TAG
+          git push origin HEAD
+          git push --tags
+
+      # Standard release
+      - name: Create Release Pull Request or Publish to npm
+        if: inputs.snapshot-tag == ''
+        uses: GarthDB/changesets-action@v1.6.8
+        with:
+          commit: "chore: release"
+          publish: pnpm release
+          oidcAuth: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

.github/workflows/release-snapshot.yml

@@ -11,42 +11,24 @@ on:
 jobs:
   get-snapshot-tag:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write
+    outputs:
+      snapshot-tag: ${{ steps.compute-tag.outputs.tag }}
     steps:
-      - name: Split branch name
-        id: split
+      - name: Compute snapshot tag
+        id: compute-tag
         env:
           BRANCH: ${{ github.ref_name }}
-        run: echo "fragment=${BRANCH##*snapshot-}" >> $GITHUB_OUTPUT
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Get last author info
-        id: author
         run: |
-          echo "authorName=$(git log -1 --pretty=format:'%an')" >> $GITHUB_OUTPUT
-          echo "authorEmail=$(git log -1 --pretty=format:'%ae')" >> $GITHUB_OUTPUT
-      - uses: moonrepo/setup-toolchain@v0
-        with:
-          auto-install: true
-      - run: moon setup
-      - run: moon run :build --query "projectSource~packages/*"
-      - name: Snapshot release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          SNAPSHOT_TAG: ${{ inputs.tag || steps.split.outputs.fragment }}
-          USERNAME: ${{ steps.author.outputs.authorName }}
-          EMAIL: ${{ steps.author.outputs.authorEmail }}
-        run: |
-          pnpm changeset version --snapshot $SNAPSHOT_TAG
-          git config --global user.name "$USERNAME"
-          git config --global user.email "$EMAIL"
-          git add .
-          git commit -m "chore: snapshot release $SNAPSHOT_TAG"
-          npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN
-          pnpm changeset publish --tag $SNAPSHOT_TAG
-          git push origin HEAD
-          git push --tags
+          if [ -n "${{ inputs.tag }}" ]; then
+            echo "tag=${{ inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=${BRANCH##*snapshot-}" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    needs: get-snapshot-tag
+    uses: ./.github/workflows/publish-packages.yml
+    with:
+      snapshot-tag: ${{ needs.get-snapshot-tag.outputs.snapshot-tag }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}

.github/workflows/release.yml

@@ -10,37 +10,6 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
   release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write # Required for npm trusted publishing (OIDC)
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      # Set up Node.js without proto to test OIDC compatibility
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20.17.0"
-      # Install npm 11.6.2 (required for OIDC) - bypassing proto
-      - run: npm install -g npm@11.6.2
-      # Install pnpm directly
-      - run: npm install -g pnpm@10.17.1
-      # Install dependencies
-      - run: pnpm install --frozen-lockfile
-      # Build packages directly (bypassing moon - only tokens package has build tasks)
-      - name: Build tokens package
-        run: |
-          cd packages/tokens
-          node tasks/buildSpectrumTokens.js
-          node tasks/buildManifest.js
-      - name: Create Release Pull Request or Publish to npm
-        id: changesets
-        uses: GarthDB/changesets-action@v1.6.8
-        with:
-          commit: "chore: release"
-          publish: pnpm release
-          oidcAuth: true # Test OIDC without proto shims
-        env:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+    uses: ./.github/workflows/publish-packages.yml
+    secrets:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}

llms.txt

@@ -210,13 +210,34 @@ pnpm generateDiffResult
 3. **Token Diff Analysis**: Compare token changes between versions
 4. **Documentation Generation**: Create docs from schemas
 5. **Migration Assistance**: Help with S1 → S2 migrations
+6. **Component Building**: Use Agent Skills to build Spectrum components correctly
+
+### Agent Skills for AI Agents
+
+The Spectrum Design Data MCP includes **Agent Skills** - markdown guides that help AI agents work with Spectrum design data:
+
+- **[Component Builder](tools/spectrum-design-data-mcp/agent-skills/component-builder.md)**: Guides agents through building Spectrum components by orchestrating MCP tools to discover schemas, find tokens, and validate configurations
+- **[Token Finder](tools/spectrum-design-data-mcp/agent-skills/token-finder.md)**: Helps agents discover the right design tokens for colors, spacing, typography, and component styling
+
+**How to Use Agent Skills:**
+1. When a user asks about building components or finding tokens, read the relevant Agent Skill
+2. Follow the step-by-step workflow provided in the skill
+3. Call the MCP tools as directed (e.g., `get-component-schema`, `find-tokens-by-use-case`)
+4. Combine tool outputs into a complete solution
+
+**Workflow Pattern:**
+- Component Building: `get-component-schema` → `get-component-tokens` → `find-tokens-by-use-case` → `validate-component-props`
+- Token Discovery: `get-design-recommendations` → `find-tokens-by-use-case` → `get-token-details`
+
+See `tools/spectrum-design-data-mcp/agent-skills/README.md` for complete documentation.
 
 ### File Patterns to Understand
 
 - `packages/tokens/src/*.json` - Token definitions
 - `packages/component-schemas/schemas/components/*.json` - Component schemas
 - `docs/*/src/**/*.ts` - Visualization tool source code
 - `tools/*/src/**/*.js` - Utility tool implementations
+- `tools/spectrum-design-data-mcp/agent-skills/*.md` - Agent Skills documentation
 
 ### Important Data Structures
 

package.json

@@ -41,7 +41,11 @@
     "remark-github": "^12.0.0"
   },
   "engines": {
-    "node": "~20.17"
+    "node": "20.17.0"
   },
-  "packageManager": "pnpm@10.17.1"
+  "packageManager": "pnpm@10.17.1",
+  "devEngines": {
+    "runtime": "20.17.0",
+    "packageManager": "pnpm@10.17.1"
+  }
 }