Skill Creator Guide

This guide helps you create effective skills for Apollo GraphQL and GraphQL development following the Agent Skills specification.

What is a Skill?

A skill is a directory containing instructions that extend an AI agent’s capabilities with specialized knowledge, workflows, or tool integrations. Skills activate automatically when agents detect relevant tasks.

Directory Structure

A skill requires at minimum a SKILL.md file:

skill-name/
├── SKILL.md              # Required - main instructions
└── references/           # Optional - detailed documentation
    ├── topic-a.md
    └── topic-b.md

SKILL.md Format

Frontmatter (Required)

---
name: skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger conditions: (1) first condition, (2) second condition.
license: MIT
compatibility: Works with Claude Code and similar AI coding assistants.
metadata:
  author: your-org
  version: "1.0.0"
allowed-tools: Read Write Edit Glob Grep
---

Frontmatter Fields

Name Rules

• Use lowercase letters, numbers, and hyphens only
• Do not start or end with a hyphen
• Do not use consecutive hyphens (--)
• Must match the parent directory name

Good: apollo-client, graphql-schema, rover Bad: Apollo-Client, -apollo, apollo--client

Description Best Practices

Write descriptions that help agents identify when to activate the skill:

# Good - specific triggers and use cases
description: >
  Guide for designing GraphQL schemas following industry best practices. Use this skill when:
  (1) designing a new GraphQL schema or API,
  (2) reviewing existing schema for improvements,
  (3) deciding on type structures or nullability,
  (4) implementing pagination or error patterns.

# Bad - vague and unhelpful
description: Helps with GraphQL stuff.

Body Content

The markdown body contains instructions the agent follows. Structure it for clarity:

Recommended Sections

1. Overview – Brief explanation of the skill’s purpose
2. Process – Step-by-step workflow (use checkboxes for multi-step processes)
3. Quick Reference – Common patterns and syntax
4. Reference Files – Links to detailed documentation
5. Key Rules – Important guidelines organized by topic
6. Ground Rules – Critical do’s and don’ts

Example Structure

# Skill Title

Brief overview of what this skill helps with.

## Process

Follow this process when working on [task]:

- [ ] Step 1: Research and understand requirements
- [ ] Step 2: Implement the solution
- [ ] Step 3: Validate the result

## Quick Reference

### Common Pattern

\`\`\`graphql
type Example {
  id: ID!
  name: String
}
\`\`\`

## Reference Files

- [Topic A](references/topic-a.md) - Detailed guide for topic A
- [Topic B](references/topic-b.md) - Detailed guide for topic B

## Key Rules

### Category One

- Rule about this category
- Another rule

### Category Two

- Rule about this category

## Ground Rules

- ALWAYS do this important thing
- NEVER do this problematic thing
- PREFER this approach over that approach

Progressive Disclosure

Structure skills to minimize context usage:

1. Metadata (~100 tokens): name and description load at startup for all skills
2. Instructions (< 5000 tokens): Full SKILL.md loads when skill activates
3. References (as needed): Files in references/ load only when required

Keep SKILL.md under 500 lines. Move detailed documentation to reference files.

Reference Files

Use references/ for detailed documentation:

references/
├── setup.md          # Installation and configuration
├── patterns.md       # Common patterns and examples
├── troubleshooting.md # Error solutions
└── api.md            # API reference

Reference files should be:

• Focused on a single topic
• Self-contained (readable without other files)
• Under 300 lines each

Link to references from SKILL.md:

## Reference Files

- [Setup](references/setup.md) - Installation and configuration
- [Patterns](references/patterns.md) - Common patterns and examples

Writing Style

Follow the Apollo Voice for all skill content:

Tone

• Approachable and helpful
• Opinionated and authoritative (prescribe the “happy path”)
• Direct and action-oriented

Language

• Use American English
• Keep language simple; avoid idioms
• Use present tense and active voice
• Use imperative verbs for instructions

Formatting

• Use sentence casing for headings
• Use code font for symbols, commands, file paths, and URLs
• Use bold for UI elements users click
• Use hyphens (-) for unordered lists

Avoid

• “Simply”, “just”, “easy” (can be condescending)
• Vague phrases like “click here”
• Semicolons (use periods instead)
• “We” unless clearly referring to Apollo

Reference Files

For Apollo GraphQL-specific guidance:

• Apollo Skills – Patterns and examples for Apollo GraphQL skills

Versioning

Use semantic versioning ("X.Y.Z") for the version field in metadata:

metadata:
  author: apollographql
  version: "1.0.0"

• Major (X): Breaking changes that alter how the skill behaves or activates (e.g., renamed triggers, removed sections, changed ground rules)
• Minor (Y): New content or capabilities that are backward-compatible (e.g., added reference files, new sections, expanded examples)
• Patch (Z): Small fixes that don’t change behavior (e.g., typo corrections, wording tweaks, formatting fixes)

Start new skills at "1.0.0".

Checklist for New Skills

Before publishing a skill, verify:

• name matches directory name and follows naming rules
• description clearly states what the skill does and when to use it
• SKILL.md is under 500 lines
• Reference files are focused and under 300 lines each
• Instructions are clear and actionable
• Code examples are correct and tested
• Ground rules use ALWAYS/NEVER/PREFER format
• Content follows Apollo Voice guidelines

Ground Rules

• ALWAYS include trigger conditions in the description (use numbered list)
• ALWAYS use checkboxes for multi-step processes
• ALWAYS link to reference files for detailed documentation
• NEVER exceed 500 lines in SKILL.md
• NEVER use vague descriptions that don’t help agents identify when to activate
• PREFER specific examples over abstract explanations
• PREFER opinionated guidance over listing multiple options
• USE allowed-tools to pre-approve tools the skill needs