When to Create a Skill

Create a skill when:

• A pattern is used repeatedly and AI needs guidance

• Project-specific conventions differ from generic best practices

• Complex workflows need step-by-step instructions

• Decision trees help AI choose the right approach

Don't create a skill when:

• Documentation already exists (create a reference instead)

• Pattern is trivial or self-explanatory

• It's a one-off task

Skill Structure

skills/{skill-name}/ ├── SKILL.md # Required - main skill file ├── assets/ # Optional - templates, schemas, examples │ ├── template.py │ └── schema.json └── references/ # Optional - links to local docs └── docs.md # Points to docs/developer-guide/*.mdx

When to Use

{Bullet points of when to use this skill}

Critical Patterns

{The most important rules - what AI MUST know}

Code Examples

{Minimal, focused examples}

Commands

{Common commands}

Resources

• Templates: See assets/ for {description}

• Documentation: See references/ for local docs

Naming Conventions

Type Pattern Examples

Generic skill {technology}

pytest , playwright , typescript

sgc-specific sgc-{component}

sgc-api , sgc-ui , sgc-sdk-check

Testing skill sgc-test-{component}

sgc-test-sdk , sgc-test-api

Workflow skill {action}-{target}

skill-creator , jira-task

Decision: assets/ vs references/

Need code templates? → assets/ Need JSON schemas? → assets/ Need example configs? → assets/ Link to existing docs? → references/ Link to external guides? → references/ (with local path)

Key Rule: references/ should point to LOCAL files (docs/developer-guide/*.mdx ), not web URLs.

Decision: sgc-Specific vs Generic

Patterns apply to ANY project? → Generic skill (e.g., pytest, typescript) Patterns are sgc-specific? → sgc-{name} skill Generic skill needs sgc info? → Add references/ pointing to sgc docs

Frontmatter Fields

Field Required Description

name

Yes Skill identifier (lowercase, hyphens)

description

Yes What + Trigger in one block

license

Yes Always Apache-2.0 for sgc

metadata.version

Yes Semantic version as string

Content Guidelines

DO

• Start with the most critical patterns

• Use tables for decision trees

• Keep code examples minimal and focused

• Include Commands section with copy-paste commands

DON'T

• Add Keywords section (agent searches frontmatter, not body)

• Duplicate content from existing docs (reference instead)

• Include lengthy explanations (link to docs)

• Add troubleshooting sections (keep focused)

• Use web URLs in references (use local paths)

Registering the Skill

After creating the skill, use the skill-registry skill to add it to the JSON registry:

Extract name and description from the new SKILL.md (assuming it's in skills/{skill-name}/SKILL.md)

NAME=$(grep '^name:' skills/{skill-name}/SKILL.md | cut -d' ' -f2) DESC=$(grep '^description:' skills/{skill-name}/SKILL.md | cut -d' ' -f2-)

Add to registry using skill-registry commands

jq --arg name "$NAME" --arg desc "$DESC" '.skills += [{"name": $name, "description": $desc}]' skills/skill-registry/assets/registry.json > temp.json && mv temp.json skills/skill-registry/assets/registry.json

This integrates with skill-registry to automatically update the JSON registry with the new skill's details.

Optionally, also add it to AGENTS.md :

| {skill-name} | {Description} | SKILL.md |

Checklist Before Creating

• Skill doesn't already exist (check skills/ )

• Pattern is reusable (not one-off)

• Name follows conventions

• Frontmatter is complete (description includes trigger keywords)

• Critical patterns are clear

• Code examples are minimal

• Commands section exists

• Added to skill-registry JSON

• Added to AGENTS.md

Resources

• Templates: See assets/ for SKILL.md template