skill-creator

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](skills/{skill-name}/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