/skill-creator

Creating Apollo GraphQL Skills

This guide provides specific guidance for creating skills in the Apollo GraphQL skills repository.

Repository Structure

Apollo skills live in the skills/ directory:

skills/
├── apollo-client/
├── apollo-connectors/
├── apollo-server/
├── graphql-schema/
└── your-new-skill/

Skill Categories

Product Skills

Skills for specific Apollo products:

• apollo-client - Apollo Client for React/web applications
• apollo-server - Apollo Server setup and configuration
• apollo-connectors - REST API integration with Connectors
• apollo-mcp-server - MCP Server for AI agents
• rover - Rover CLI for graph management

Convention Skills

Skills for GraphQL conventions and best practices:

• graphql-schema - Schema design patterns
• graphql-operations - Query and mutation patterns

Description Patterns

Use consistent trigger patterns in descriptions:

# Product skill pattern
description: >
  Help users build [what] with [product]. Use this skill when:
  (1) setting up [product] in a new project,
  (2) implementing [common feature],
  (3) troubleshooting [product] errors,
  (4) working with files containing [identifier].

# Convention skill pattern
description: >
  Guide for [topic] following industry best practices. Use this skill when:
  (1) designing new [thing],
  (2) reviewing existing [thing] for improvements,
  (3) implementing [pattern],
  (4) ensuring [quality aspect].

MCP Tool Integration

If GraphOS MCP tools are available, reference them in your skill:

## MCP Tools

If GraphOS MCP Tools are available, use them:
- **apollo_docs_search**: Search for relevant documentation
- **apollo_docs_read**: Read specific documentation pages by slug

**Documentation paths by topic:**
- Topic A: `/graphos/path/to/topic-a`
- Topic B: `/graphos/path/to/topic-b`

Process Structure

Use a consistent process structure with checkboxes:

## Process

Follow this process. **DO NOT skip any steps.**

### Step 1: Research

- [ ] Understand the requirements
- [ ] Ask the user for clarification if needed
- [ ] Fetch relevant documentation
- [ ] DO NOT write code until research is complete

### Step 2: Implement

- [ ] Create the solution using patterns below
- [ ] Follow the reference files for detailed guidance

### Step 3: Validate

- [ ] Run validation commands
- [ ] Fix any errors before proceeding

### Step 4: Test

- [ ] Create or update tests
- [ ] Verify the solution works correctly

Code Examples

GraphQL Schema Examples

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
}

TypeScript Examples

import { ApolloClient, InMemoryCache } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://api.example.com/graphql',
  cache: new InMemoryCache(),
});

Rover CLI Examples

# Publish a subgraph
rover subgraph publish my-graph@current \
  --name products \
  --schema ./schema.graphql

# Run local development
rover dev --supergraph-config supergraph.yaml

Reference File Organization

Organize reference files by topic:

references/
├── setup.md           # Installation and quick start
├── queries.md         # Query patterns (for client skills)
├── mutations.md       # Mutation patterns (for client skills)
├── resolvers.md       # Resolver patterns (for server skills)
├── caching.md         # Cache configuration
├── error-handling.md  # Error handling patterns
└── troubleshooting.md # Common errors and solutions

Security Patterns

Many Apollo skills generate configuration that has security implications. When a skill touches auth, caching, CORS, data exposure, or secrets, follow these patterns.

Label security sections explicitly

Use ## Security as the heading — not "Private data", "Customization", or "Advanced". The LLM needs the literal word "Security" to categorize the content correctly.

## Security

> **Security: data leakage risk.** Response caching is PUBLIC by default.
> Any field not explicitly marked `scope: PRIVATE` with a configured
> `private_id` will be shared across all users. User-specific fields
> (profile data, preferences, bookmarks) MUST use PRIVATE scope.

Place warnings at the point of risk

Put security guidance directly next to the config that creates the risk. Do not rely on a separate reference file alone.

### Caching scope

> **Security: cross-user data leakage.** The default scope is PUBLIC —
> all users share the same cache entries. You MUST identify which fields
> are user-specific and mark them `scope: PRIVATE` before enabling caching.

\`\`\`yaml
response_cache:
  enabled: true
  subgraph:
    subgraphs:
      accounts:
        private_id: "user_id"  # Required for PRIVATE-scoped fields
\`\`\`

Require data model understanding

When correct configuration depends on knowing the user's data model, instruct the LLM to ask — never guess:

## Ground Rules

- ALWAYS ask which fields contain user-specific data before generating cache config
- NEVER assume a field is safe to cache publicly without explicit confirmation

Add security items to validation checklists

Every security-sensitive feature must have corresponding validation checks:

## Security

- [ ] **Private fields identified**: All user-specific fields use `scope: PRIVATE`
- [ ] **private_id configured**: Every subgraph serving PRIVATE data has `private_id` set
- [ ] **Debug disabled** (production): `debug` is absent or `false`
- [ ] **Endpoints not publicly exposed**: Internal endpoints bind to `127.0.0.1`, not `0.0.0.0`
- [ ] **Secrets use env vars**: No hardcoded credentials, tokens, or keys

Security ground rules

Use ALWAYS/NEVER for security requirements — these are the strongest signal to the LLM:

- NEVER enable debug mode in production config
- NEVER bind internal endpoints to 0.0.0.0 in production
- ALWAYS use environment variables for secrets, credentials, and keys
- ALWAYS ask the user which fields are user-specific before configuring cache scope
- NEVER generate cache config that assumes all data is public without confirming with the user

Ground Rules Format

Use consistent formatting for ground rules:

## Ground Rules

- NEVER make up syntax not in the specification
- NEVER skip validation steps
- ALWAYS ask for clarification when requirements are unclear
- ALWAYS validate with appropriate commands after changes
- PREFER [recommended approach] over [alternative]
- USE [tool/pattern] for [specific use case]

Documentation Links

Include links to official Apollo documentation:

## Resources

- [Apollo Client Documentation](https://www.apollographql.com/docs/react/)
- [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
- [Apollo Connectors Documentation](https://www.apollographql.com/docs/graphos/schema-design/connectors/)
- [Rover CLI Documentation](https://www.apollographql.com/docs/rover/)

Validation Checklist

Before submitting a new Apollo skill:

• Skill follows the Agent Skills specification
• Description includes numbered trigger conditions
• Code examples use current API versions
• Commands include required flags and options
• Error messages reference troubleshooting guide
• Links to official Apollo documentation are correct
• Content follows Apollo Voice guidelines
• Security-sensitive features have a labeled ## Security section
• Security warnings appear at the point of risk, not only in reference files
• Validation checklist includes security checks for every security-sensitive feature
• Skill instructs the LLM to ask about the data model before generating security-sensitive config