Display Studio Skills

A curated skill collection for AI agents, including first-party skills and vendored framework/CMS best practices for use with the Agent Skills ecosystem and skills.sh.

Repository pattern

• One directory per skill: skills/<skill-name>/
• Skill entrypoint: skills/<skill-name>/SKILL.md
• Modular rules: skills/<skill-name>/rules/*.md
• One skill per domain where it helps: router SKILL.md + references/ (generated from vendors by scripts/sync-vendored.mjs) + optional first-party rules/ (gsap, sanity, animation)
• Upstream vendors tracked as submodules under vendor/

Included skills

First-party (Display Studio)

• gsap: one skill for all GSAP topics (core, timeline, ScrollTrigger, plugins, React, frameworks, utils, performance, debug). Router + references/ generated from greensock/gsap-skills (MIT) with display studio additions. Replaces the former gsap-* skills: install with --skill gsap.
• animation: web animation in one skill. First-party conventions (scroll-reveal presets, Lenis + GSAP ticker, page transitions, reduced motion, cleanup, Nuxt and vanilla adapters) in rules/, plus Emil Kowalski's guides (when/how to animate, easing, review, audit, gestures) in references/. Replaces motion-conventions and the emil-* skills: install with --skill animation.
• nuxt-sanity: @nuxtjs/sanity module integration best practices for Nuxt 3 + Sanity CMS. Covers useSanityQuery, useLazySanityQuery, useSanity, SanityImage, SanityContent (Portable Text), visual editing with stega, TypeScript typegen, named clients, Nitro server routes, CORS, caching patterns, and dynamic sitemap generation.
• nuxt-seo: @nuxtjs/robots best practices for Nuxt 3. Covers robots.txt configuration, blockNonSeoBots, blockAiBots, per-page noindex via definePageMeta, route rules, useRobotsRule composable, environment-based indexing, and llms.txt for AI tool documentation access.
• ruby: core Ruby language best practices (independent of any framework) covering syntax and types, collections/Enumerable, blocks/procs/lambdas, OOP and modules, metaprogramming, Bundler/gems, testing (RSpec/Minitest), and style/typing tooling (RuboCop, RBS, Steep, ruby-lsp).
• ruby-on-rails: full-stack Rails 8.1 best practices covering MVC lifecycle, Active Record (incl. multiple databases/sharding), routing, views, forms, background jobs, mailer, WebSockets, Active Storage, security (incl. the Rails 8 authentication generator), testing, performance, Kamal/Thruster deployment, engines/generators, and debugging.
• sanity-schema-accelerator: low-token Sanity schema generator for object blocks, pageBuilder arrays, singleton pages, and repeatable pages using your Display Studio conventions.
• shopify-development: Shopify apps, extensions, themes, GraphQL API, webhooks, Liquid templating, billing, metafields (API v2026-01).
• tailwind: Tailwind CSS v4 best practices covering utility-first patterns, @theme variables, responsive design, dark mode, custom styles, performance, accessibility, and a Figma → Tailwind theme generation workflow (paste Figma CSS variables, get @theme CSS files organized by category: colors, typography, spacing, radius/shadows, breakpoints).

Vendored from antfu/skills

• nuxt
• vue
• vite

Vendored from sanity-io/agent-toolkit

Compacted into skills/sanity (MIT): sanity-best-practices, content-modeling-best-practices, seo-aeo-best-practices, content-experimentation-best-practices as references/ topics. Install with --skill sanity.

Vendored from vercel-labs/agent-skills

• web-design-guidelines

Vendored from Shopify/Shopify-AI-Toolkit

• shopify: one skill for every Shopify developer surface (Admin, Storefront, Functions, Polaris, Hydrogen, Liquid, CLI, ...). Upstream's single skill replaces the former shopify-* skills. Upstream telemetry is disabled in the vendored scripts.
• ucp

Vendored from JuliusBrussee/skills

• caveman
• deslopify
• grill-me
• junior-to-senior

Vendored from emilkowalski/skills

MIT licensed, © Emil Kowalski. Web animation subset, compacted into skills/animation (references/): emil-design-eng, animate, review-animations, improve-animations, find-animation-opportunities, animation-vocabulary, apple-design.

Vendored from dietrichgebert/ponytail

• ponytail

Install (skills CLI)

Install one skill from this repository:

npx skills add <owner>/<repo> --skill gsap

Install a specific first-party or vendored skill:

npx skills add <owner>/<repo> --skill nuxt-sanity
npx skills add <owner>/<repo> --skill nuxt
npx skills add <owner>/<repo> --skill sanity

Install all skills from this repository:

npx skills add <owner>/<repo> --skill '*'

List discoverable skills before install:

npx skills add <owner>/<repo> --list

Install all skills from a single vendor

The --skill flag only accepts exact skill names (repeatable) or '*' for the entire repo — there is no prefix/glob shorthand like --skill 'shopify-*'. To install every skill from one vendor, list each of its skill names explicitly:

npx skills add display-design-studio/skills \
  --skill shopify --skill ucp

Use the vendor lists in Included skills above to get the exact names for other vendors:

• antfu/skills: nuxt, vue, vite
• sanity-io/agent-toolkit: compacted into sanity
• vercel-labs/agent-skills: web-design-guidelines
• Shopify/Shopify-AI-Toolkit: shopify, ucp
• JuliusBrussee/skills: caveman, deslopify, grill-me, junior-to-senior
• emilkowalski/skills: compacted into animation

Alternatively, copy the vendor's skills directly from this repo's vendor/ submodules (read-only mirrors of upstream), the same way SYNC.md re-copies them into skills/:

cp -R vendor/shopify-ai-toolkit/skills/* /path/to/project/mnt/skills/vendor/

See SYNC.md for the full per-skill cp -R list for each vendor.

Attribution and authorship

• First-party skill frontmatter uses only name + description (Anthropic spec). Attribution is tracked in rules/_coverage-map.md.
• Vendored skills keep their upstream metadata and attribution.
• Sources are preserved via vendor/ submodules for update traceability.

Figma → Tailwind workflow

The tailwind skill includes a purpose-built agent workflow to translate Figma CSS variables into Tailwind v4 @theme files. See skills/tailwind/rules/figma-to-theme-workflow.md for the full instructions.

How to use:

1. Export CSS variables from Figma (via "Variables to CSS" plugin or Dev Mode copy)
2. Paste them in chat and ask the agent to generate the Tailwind theme files
3. The agent classifies variables (colors, typography, spacing, radius, shadows, breakpoints) and writes the corresponding @theme CSS files using the templates in skills/tailwind/figma-tokens/

Consuming skills in a project repo

Recommended structure

Place skills under mnt/skills/ (or the path configured in your agent environment). Separate first-party from vendored for easier sync management:

mnt/skills/
├── user/                  # first-party, project-specific skills
│   ├── gsap/
│   │   └── SKILL.md
│   └── nuxt-sanity/
│       └── SKILL.md
└── vendor/                # upstream-synced, treat as read-only
    ├── content-modeling-best-practices/
    │   └── SKILL.md
    └── vite/
        └── SKILL.md

The agent will scan all SKILL.md files under the configured root. The description field in each file's frontmatter is what Claude reads to decide whether to load a skill automatically — so it is the highest-leverage thing to get right.

How to add a skill

1. Install via CLI:

   npx skills add display-design-studio/skills --skill gsap

   or copy the directory manually into mnt/skills/user/ (first-party) or mnt/skills/vendor/ (upstream).

2. Verify the SKILL.md frontmatter has a meaningful description. If it doesn't, see the section below.

3. No registration needed — the agent discovers skills from the file system automatically.

How to update skills

Use the skills CLI's dedicated update command (alias: upgrade) to pull the latest version of installed skills:

# Update all skills in the current project
npx skills update -p

# Update one or more specific skills
npx skills update gsap
npx skills update gsap nuxt-sanity

# Skip the scope prompt (auto-detects project vs. global)
npx skills update -y

Use -g/--global instead of -p/--project to update global (user-level) skills.

Existing skill files are overwritten in place. First-party customisations (e.g. edited description fields) will be lost — back them up first if needed.

Customising description for auto-triggering

Claude decides which skills to load based solely on the description field in SKILL.md frontmatter. A weak description means the skill is silently ignored even when it would be useful.

Signs a description needs work:

• It reads like a product pitch ("A comprehensive guide to…") with no concrete nouns
• It omits the actual technology names, file types, or CLI commands
• It doesn't list the user-facing trigger words someone would naturally type

Pattern to follow:

description: |
  Use this skill for <primary technology> tasks. Triggers include:
  <trigger word>, <trigger word>, <trigger word>.
  Also relevant for: <secondary concept>, <secondary concept>.

Real example (before/after for vite):

# Before (weak — no triggers)
description: Best practices for Vite projects.

# After (strong — concrete triggers)
description: |
  Use for any Vite build tooling question. Triggers: vite.config.ts, HMR,
  Rollup plugin, library mode, SSR build, vitest config. Also covers
  framework-specific setups: Vue, React, Svelte, Nuxt, SvelteKit.

Rule of thumb: if you can picture a developer typing the trigger word in a chat message, it belongs in the description.

⚠️ For vendored skills, only edit the description field — leave all other content intact to keep upstream diffs clean. See the sync section below.

Updating vendored skills without losing customisations

Vendored skill content may be overwritten when you pull upstream changes. To protect custom description fields:

1. Before syncing, export your custom descriptions:

   grep -r "^description:" mnt/skills/vendor/ > .skill-descriptions.bak

2. Run the sync (see SYNC.md for the full workflow):

   git submodule update --remote --init --recursive
   # then re-copy from vendor/ into mnt/skills/vendor/

3. After syncing, re-apply your custom descriptions. If you keep them in a patch file (e.g. patches/skill-descriptions.patch), a single git apply patches/skill-descriptions.patch restores everything.

A description-improvements.patch for the vendored skills in this repo is included in patches/ — apply it after any upstream sync:

git apply patches/description-improvements.patch

---

Authoring guidelines (first-party skills)

• Keep SKILL.md concise as the skill router and index.
• Put detailed implementation guidance in rules/ with focused files.
• Prefer actionable rules with:
  • why it matters
  • incorrect pattern
  • correct pattern
  • links to official docs
• Keep a _coverage-map.md per skill to track source coverage.

Checklist for new first-party skills

1. Create skills/<skill-name>/SKILL.md.
2. Create skills/<skill-name>/rules/_sections.md.
3. Create skills/<skill-name>/rules/_coverage-map.md.
4. Create modular rule files under skills/<skill-name>/rules/.
5. Use prefixed rule naming:
   • core-*, plugin-*, tools-*, perf-*, a11y-*, debug-*.
6. Ensure each rule file includes:
   • why it matters
   • incorrect pattern
   • correct pattern
   • official docs links
7. Update this README.md with the new skill.

Updating vendored skills

Update submodules to pull latest upstream content:

git submodule update --remote --init --recursive

Then re-copy needed skills from vendor/*/skills/* into skills/* and review diffs.

For a ready-to-run workflow, see SYNC.md.