Agent Skills Writing Skill

Standards and patterns for authoring AI agent skills in this repository.

Skill Locations

| Location | Purpose | Audience | |----------|---------|---------| | skills/sgds-utilities/ | All SGDS utility classes in one consolidated skill with a reference file per utility category | external | | skills/sgds-components/ | All 46 SGDS web components in one consolidated skill with a reference file per component | external | | .github/skills/ | Internal tools for SGDS maintainers | internal (no audience field) |

Folder naming convention: All skills/ folders use a domain prefix so agents and users can discover them by category:

sgds-utilities — consolidated skill for all SGDS utility classes (sgds: Tailwind prefix); reference files in sgds-utilities/reference/
sgds-components — consolidated skill for all SGDS web components (<sgds-*>); reference files in sgds-components/reference/

SKILL.md Frontmatter

---
name: sgds-utilities-{skill-name}   # or sgds-components-{skill-name}
description: "One sentence. What the skill teaches. Include trigger keywords (Use when users ask about...)."
metadata:
  author: singapore-design-system
  version: "0.0.0"
  audience: external       # external skills only; omit for internal skills
  category: {category}     # e.g. color, border, spacing, typography, component
---

Important: Always quote the description value. YAML will error if the value contains a colon (e.g., sgds: prefix).

File starts directly with --- — no wrapping code fences
Version stays "0.0.0" until officially released; bump major version on breaking changes

Folder Structure

Simple skill (no reference files needed, under ~500 lines):

skills/utilities-{name}/
└── SKILL.md

skills/components-{name}/
└── SKILL.md

Complex skill (semantic categories, would exceed ~500 lines):

skills/utilities-{name}/
├── SKILL.md          ← navigation hub + Quick Decision Guide only
└── reference/
    ├── base.md
    ├── primary.md
    ├── danger.md
    └── ...

Consolidated skill (many related items grouped into one skill with a reference file per item):

skills/sgds-components/
├── SKILL.md          ← setup content + component index table with links to reference/
└── reference/
    ├── accordion.md
    ├── alert.md
    ├── button.md
    └── ...            ← one file per component, no frontmatter, no Prerequisites section

Use the consolidated pattern when a domain has many parallel items (e.g., all SGDS web components) that would otherwise create dozens of top-level skill folders. The consolidated SKILL.md acts as both the setup guide and the navigation index.

When to Extract Reference Files

Split into reference/ when any of these are true:

SKILL.md would exceed ~500 lines with all token documentation included
The skill covers multiple semantic categories (primary, danger, success, etc.) that each have enough depth for their own file
Different categories have meaningfully different design semantics worth documenting separately
The domain has many parallel items that are better served by a consolidated skill (use the consolidated pattern above)

Do not extract if the skill is a single focused topic (e.g., spacing utilities, opacity).

Consolidated Skill Reference Files

Reference files in a consolidated skill differ from standalone SKILL.md files:

No YAML frontmatter — reference files start directly with the # heading
No Prerequisites section — setup instructions live only in the parent SKILL.md; reference files do not duplicate them
Cross-references — links to the parent SKILL.md use ../SKILL.md; links to sibling reference files use ./other.md or just other.md
Content — everything else from the original SKILL.md (Quick Decision Guide, API Summary, Slots, Events, For AI agents) is preserved verbatim

Utility Skill Structure (with references)

Model: see skills/utilities-background-color/SKILL.md and skills/utilities-border-color/SKILL.md.

The SKILL.md is a navigation hub and decision guide — not an example gallery.

# {Name} Utilities Skill

One-line description of what it helps with.

## Prerequisites
## Core Concept
## Token Categories Overview   ← conceptual bullets + links to reference files; NO long code examples
## Quick Decision Guide         ← decision tree (Step 1 / Step 2 / Step 3)
## Reference Documentation      ← one entry per reference file (name, covers, use for)

---
**For AI Agents**: Key principles summary (numbered list, ~8–10 items)

Rules for SKILL.md content

No long code examples in SKILL.md — they belong in reference files
Token Categories Overview may include 1–2 short inline examples to illustrate a pattern, not to demonstrate every token
Quick Decision Guide uses bullet lists and → token format, not code blocks
Reference Documentation section links to every reference file with a Covers: and Use for: line

Component Skill Structure

Model: see skills/sgds-components/reference/button.md.

Component skills document an <sgds-*> element's usage. Their SKILL.md structure differs from utility skills:

# SGDS {Name} Component Skill

One-line role of the component and when to prefer it over a native element.

## Prerequisites
## Quick Decision Guide   ← variant/tone/size/mode decision tree
## API Summary            ← all attributes as a compact table (name | type | default | purpose)
## Slots                  ← slot name + purpose table
## Events                 ← event name | when fired | React prop
## Reference Documentation

---
**For AI agents**: Key rules — default element to reach for, dangerous combinations to avoid,
                   related components to mention.

Rules specific to component skills

Lead with the element tag, not attribute tables — the first code example in Quick Decision Guide must be <sgds-{name}> HTML
Slots get a dedicated table in the hub — they are not optional documentation
Events table lists event name and when it fires only — framework-specific syntax (React prop names, Vue @event, Angular (event)) belongs in sgds-components-setup, not the individual component skill
Reference components-setup in Prerequisites — every component skill's Prerequisites section links to sgds-components-setup
Mention sibling components where relevant (e.g., <sgds-icon-button> from a <sgds-button> skill)
No library-first note needed — this skill is the library component; instead, note when to use raw utilities to extend it
HTML examples in reference/ may combine the component's own attributes freely — the single-token isolation rule applies to utility skills only

Reference File Structure

Model: see any file in skills/utilities-background-color/reference/.

# {Category} {Skill Name} Reference

**Meaning**: One phrase  
**Usage**: One phrase

## Design Semantics

- Bullet list explaining the intent and when to use this category
- Applied at which level (component only / page only / both)
- Contrast with adjacent categories if helpful (e.g., neutral vs purple/cyan)

## Available Tokens

### `sgds:{prefix}-{category}-{modifier}`
**One-line description.**

**When to use:**
- Bullet list of specific use cases

```html
<div class="sgds:{THIS-TOKEN-ONLY}">
  label
</div>

(Repeat for each token in the category)

Common Patterns

Note: Use library components like <sgds-alert>, <sgds-badge> when available. {Category} tokens are for creating custom components when library components don't meet your needs.

Pattern Name

(pattern example)

Best Practices ← optional; include only when there are genuine gotchas

Shared Semantics Extraction

When two or more skills share the same suffix modifier vocabulary (e.g., default, emphasis, muted, fixed-light, fixed-dark, inverse), extract the definitions into a dedicated shared skill rather than duplicating them.

Pattern used: skills/utilities-color-semantics/SKILL.md is the shared reference for all suffix modifiers used by utilities-background-color, utilities-border-color, and utilities-text-color.

Each consumer skill replaces its duplicated prose with:

For full definitions of suffix modifiers, see **[`utilities-color-semantics`](../utilities-color-semantics/SKILL.md)**.

Apply this pattern whenever you notice the same conceptual definitions appearing verbatim across multiple SKILL.md files.

Library-First Principle

Every reference/ file must include a library-first note at the top of the Common Patterns section:

> **Note**: Use library components like `<sgds-{component}>` when available.
> {Category} tokens are for creating custom components when library components don't meet your needs.

Name specific relevant library components (e.g., <sgds-alert> in danger/warning files, <sgds-badge> in neutral/purple/cyan files). This reminds developers to check the component library before reaching for raw utility tokens.

Eval Workspace Convention

When running the skill-creator eval loop for any skill in skills/, always place the workspace directory under:

test/skills/{skill-folder-name}-workspace/

For example:

skills/components-masthead/ → test/skills/components-masthead-workspace/
skills/utilities-spacing/ → test/skills/utilities-spacing-workspace/

This keeps generated eval artefacts (iteration dirs, benchmark.json, grading files, feedback.json) out of src/ and co-located with the project's other test outputs in test/.

Registering a New Skill

Utilities skills

All SGDS utility categories live in the consolidated skills/sgds-utilities/ skill. To add a new utility category reference:

Create skills/sgds-utilities/reference/{category-name}.md — no frontmatter, no Prerequisites section.
- If the category has multiple sub-topics, create a hub file reference/{category-name}.md + a subfolder reference/{category-name}/ with individual topic files.
Add a row for the category in the ## Available Utilities table in skills/sgds-utilities/SKILL.md.
Update the description frontmatter of skills/sgds-utilities/SKILL.md to include the new category.
Update CLAUDE.md if the description blurb for sgds-utilities needs updating.

Component skills

All SGDS web components live in the consolidated skills/sgds-components/ skill. To add a new component reference:

Create skills/sgds-components/reference/{component-name}.md — no frontmatter, no Prerequisites section.
Add a row for the component in the ## Available Components table in skills/sgds-components/SKILL.md.
Update the description frontmatter of skills/sgds-components/SKILL.md to include the new component name.
Update CLAUDE.md if the description blurb for sgds-components needs updating.

Checklist for New Skills

Before considering a skill complete:

All skills

[ ] SKILL.md starts with --- frontmatter (no wrapping fences)
[ ] version: "0.0.0" set
[ ] description value is quoted (required if it contains a colon)
[ ] SKILL.md is a navigation hub — no long code blocks
[ ] Reference files exist if skill covers multiple semantic categories or would exceed ~500 lines
[ ] Registered in .github/copilot-instructions.md

Utilities skills only

[ ] All HTML examples contain only the token(s) for that file's category
[ ] Every Common Patterns section has a library-first note
[ ] Shared modifier definitions link to color-semantics.md, not duplicated
[ ] Row added to ## Available Utilities table in skills/sgds-utilities/SKILL.md
[ ] Category name added to sgds-utilities frontmatter description

Component skills only

[ ] First code example in hub is raw <sgds-*> HTML
[ ] Slots documented in a table in the hub
[ ] Events table includes React prop name
[ ] React import path mentioned if wrapper exists in lib/react/
[ ] Related/sibling components noted

skill-creator — General methodology for drafting, evaluating, and iterating on any skill. Use alongside this guide: skill-creator covers the process, agent-skills-writing covers SGDS-specific conventions
token-workflow — Adding or modifying design tokens
tailwind-mapping — Mapping CSS variables to Tailwind utilities
Copilot Instructions — Where skills are registered

Agent Skills Writing Skill

Standards and patterns for authoring AI agent skills in this repository.

Skill Locations

Folder naming convention: All skills/ folders use a domain prefix so agents and users can discover them by category:

sgds-utilities — consolidated skill for all SGDS utility classes (sgds: Tailwind prefix); reference files in sgds-utilities/reference/
sgds-components — consolidated skill for all SGDS web components (<sgds-*>); reference files in sgds-components/reference/

SKILL.md Frontmatter

---
name: sgds-utilities-{skill-name}   # or sgds-components-{skill-name}
description: "One sentence. What the skill teaches. Include trigger keywords (Use when users ask about...)."
metadata:
  author: singapore-design-system
  version: "0.0.0"
  audience: external       # external skills only; omit for internal skills
  category: {category}     # e.g. color, border, spacing, typography, component
---

Important: Always quote the description value. YAML will error if the value contains a colon (e.g., sgds: prefix).

File starts directly with --- — no wrapping code fences
Version stays "0.0.0" until officially released; bump major version on breaking changes

Folder Structure

Simple skill (no reference files needed, under ~500 lines):

skills/utilities-{name}/
└── SKILL.md

skills/components-{name}/
└── SKILL.md

Complex skill (semantic categories, would exceed ~500 lines):

skills/utilities-{name}/
├── SKILL.md          ← navigation hub + Quick Decision Guide only
└── reference/
    ├── base.md
    ├── primary.md
    ├── danger.md
    └── ...

Consolidated skill (many related items grouped into one skill with a reference file per item):

skills/sgds-components/
├── SKILL.md          ← setup content + component index table with links to reference/
└── reference/
    ├── accordion.md
    ├── alert.md
    ├── button.md
    └── ...            ← one file per component, no frontmatter, no Prerequisites section

When to Extract Reference Files

Split into reference/ when any of these are true:

SKILL.md would exceed ~500 lines with all token documentation included
The skill covers multiple semantic categories (primary, danger, success, etc.) that each have enough depth for their own file
Different categories have meaningfully different design semantics worth documenting separately
The domain has many parallel items that are better served by a consolidated skill (use the consolidated pattern above)

Do not extract if the skill is a single focused topic (e.g., spacing utilities, opacity).

Consolidated Skill Reference Files

Reference files in a consolidated skill differ from standalone SKILL.md files:

No YAML frontmatter — reference files start directly with the # heading
No Prerequisites section — setup instructions live only in the parent SKILL.md; reference files do not duplicate them
Cross-references — links to the parent SKILL.md use ../SKILL.md; links to sibling reference files use ./other.md or just other.md
Content — everything else from the original SKILL.md (Quick Decision Guide, API Summary, Slots, Events, For AI agents) is preserved verbatim

Utility Skill Structure (with references)

Model: see skills/utilities-background-color/SKILL.md and skills/utilities-border-color/SKILL.md.

The SKILL.md is a navigation hub and decision guide — not an example gallery.

# {Name} Utilities Skill

One-line description of what it helps with.

## Prerequisites
## Core Concept
## Token Categories Overview   ← conceptual bullets + links to reference files; NO long code examples
## Quick Decision Guide         ← decision tree (Step 1 / Step 2 / Step 3)
## Reference Documentation      ← one entry per reference file (name, covers, use for)

---
**For AI Agents**: Key principles summary (numbered list, ~8–10 items)

Rules for SKILL.md content

No long code examples in SKILL.md — they belong in reference files
Token Categories Overview may include 1–2 short inline examples to illustrate a pattern, not to demonstrate every token
Quick Decision Guide uses bullet lists and → token format, not code blocks
Reference Documentation section links to every reference file with a Covers: and Use for: line

Component Skill Structure

Model: see skills/sgds-components/reference/button.md.

Component skills document an <sgds-*> element's usage. Their SKILL.md structure differs from utility skills:

# SGDS {Name} Component Skill

One-line role of the component and when to prefer it over a native element.

## Prerequisites
## Quick Decision Guide   ← variant/tone/size/mode decision tree
## API Summary            ← all attributes as a compact table (name | type | default | purpose)
## Slots                  ← slot name + purpose table
## Events                 ← event name | when fired | React prop
## Reference Documentation

---
**For AI agents**: Key rules — default element to reach for, dangerous combinations to avoid,
                   related components to mention.

Rules specific to component skills

Lead with the element tag, not attribute tables — the first code example in Quick Decision Guide must be <sgds-{name}> HTML
Slots get a dedicated table in the hub — they are not optional documentation
Events table lists event name and when it fires only — framework-specific syntax (React prop names, Vue @event, Angular (event)) belongs in sgds-components-setup, not the individual component skill
Reference components-setup in Prerequisites — every component skill's Prerequisites section links to sgds-components-setup
Mention sibling components where relevant (e.g., <sgds-icon-button> from a <sgds-button> skill)
No library-first note needed — this skill is the library component; instead, note when to use raw utilities to extend it
HTML examples in reference/ may combine the component's own attributes freely — the single-token isolation rule applies to utility skills only

Reference File Structure

Model: see any file in skills/utilities-background-color/reference/.

# {Category} {Skill Name} Reference

**Meaning**: One phrase  
**Usage**: One phrase

## Design Semantics

- Bullet list explaining the intent and when to use this category
- Applied at which level (component only / page only / both)
- Contrast with adjacent categories if helpful (e.g., neutral vs purple/cyan)

## Available Tokens

### `sgds:{prefix}-{category}-{modifier}`
**One-line description.**

**When to use:**
- Bullet list of specific use cases

```html
<div class="sgds:{THIS-TOKEN-ONLY}">
  label
</div>

(Repeat for each token in the category)

Common Patterns

Note: Use library components like <sgds-alert>, <sgds-badge> when available. {Category} tokens are for creating custom components when library components don't meet your needs.

Pattern Name

(pattern example)

Best Practices ← optional; include only when there are genuine gotchas

Shared Semantics Extraction

Each consumer skill replaces its duplicated prose with:

For full definitions of suffix modifiers, see **[`utilities-color-semantics`](../utilities-color-semantics/SKILL.md)**.

Apply this pattern whenever you notice the same conceptual definitions appearing verbatim across multiple SKILL.md files.

Library-First Principle

Every reference/ file must include a library-first note at the top of the Common Patterns section:

> **Note**: Use library components like `<sgds-{component}>` when available.
> {Category} tokens are for creating custom components when library components don't meet your needs.

Eval Workspace Convention

When running the skill-creator eval loop for any skill in skills/, always place the workspace directory under:

test/skills/{skill-folder-name}-workspace/

For example:

skills/components-masthead/ → test/skills/components-masthead-workspace/
skills/utilities-spacing/ → test/skills/utilities-spacing-workspace/

This keeps generated eval artefacts (iteration dirs, benchmark.json, grading files, feedback.json) out of src/ and co-located with the project's other test outputs in test/.

Registering a New Skill

Utilities skills

All SGDS utility categories live in the consolidated skills/sgds-utilities/ skill. To add a new utility category reference:

Create skills/sgds-utilities/reference/{category-name}.md — no frontmatter, no Prerequisites section.
- If the category has multiple sub-topics, create a hub file reference/{category-name}.md + a subfolder reference/{category-name}/ with individual topic files.
Add a row for the category in the ## Available Utilities table in skills/sgds-utilities/SKILL.md.
Update the description frontmatter of skills/sgds-utilities/SKILL.md to include the new category.
Update CLAUDE.md if the description blurb for sgds-utilities needs updating.

Component skills

All SGDS web components live in the consolidated skills/sgds-components/ skill. To add a new component reference:

Create skills/sgds-components/reference/{component-name}.md — no frontmatter, no Prerequisites section.
Add a row for the component in the ## Available Components table in skills/sgds-components/SKILL.md.
Update the description frontmatter of skills/sgds-components/SKILL.md to include the new component name.
Update CLAUDE.md if the description blurb for sgds-components needs updating.

Checklist for New Skills

Before considering a skill complete:

All skills

[ ] SKILL.md starts with --- frontmatter (no wrapping fences)
[ ] version: "0.0.0" set
[ ] description value is quoted (required if it contains a colon)
[ ] SKILL.md is a navigation hub — no long code blocks
[ ] Reference files exist if skill covers multiple semantic categories or would exceed ~500 lines
[ ] Registered in .github/copilot-instructions.md

Utilities skills only

[ ] All HTML examples contain only the token(s) for that file's category
[ ] Every Common Patterns section has a library-first note
[ ] Shared modifier definitions link to color-semantics.md, not duplicated
[ ] Row added to ## Available Utilities table in skills/sgds-utilities/SKILL.md
[ ] Category name added to sgds-utilities frontmatter description

Component skills only

[ ] First code example in hub is raw <sgds-*> HTML
[ ] Slots documented in a table in the hub
[ ] Events table includes React prop name
[ ] React import path mentioned if wrapper exists in lib/react/
[ ] Related/sibling components noted

skill-creator — General methodology for drafting, evaluating, and iterating on any skill. Use alongside this guide: skill-creator covers the process, agent-skills-writing covers SGDS-specific conventions
token-workflow — Adding or modifying design tokens
tailwind-mapping — Mapping CSS variables to Tailwind utilities
Copilot Instructions — Where skills are registered

Adoption

govtechsg/agent-skills-writing

$ install --global

Security Scan Results

SKILL.md

Agent Skills Writing Skill

Skill Locations

SKILL.md Frontmatter

Folder Structure

When to Extract Reference Files

Consolidated Skill Reference Files

Utility Skill Structure (with references)

Rules for SKILL.md content

Component Skill Structure

Rules specific to component skills

Reference File Structure

Common Patterns

Pattern Name

Best Practices ← optional; include only when there are genuine gotchas

See Also

Shared Semantics Extraction

Library-First Principle

Eval Workspace Convention

Registering a New Skill

Utilities skills

Component skills

Checklist for New Skills

Related

Related Skills

govtechsg/sgds-components

govtechsg/sgds-forms

govtechsg/sgds-layouts

govtechsg/sgds-templates

govtechsg/agent-skills-writing

$ install --global

Security Scan Results

SKILL.md

Agent Skills Writing Skill

Skill Locations

SKILL.md Frontmatter

Folder Structure

When to Extract Reference Files

Consolidated Skill Reference Files

Utility Skill Structure (with references)

Rules for SKILL.md content

Component Skill Structure

Rules specific to component skills

Reference File Structure

Common Patterns

Pattern Name

Best Practices ← optional; include only when there are genuine gotchas

See Also

Shared Semantics Extraction

Library-First Principle

Eval Workspace Convention

Registering a New Skill

Utilities skills

Component skills

Checklist for New Skills

Related

Related Skills

govtechsg/sgds-components

govtechsg/sgds-forms

govtechsg/sgds-layouts

govtechsg/sgds-templates