/forge-graphql-skill

description: Scaffold a complete Claude Code skill (commands + types + client) from a GraphQL endpoint or local schema file
argument-hint: <name> <graphql-endpoint-url> [--schema-introspection] [--schema-file <path>] [--auth-header <header>]
allowed-tools: Bash, Read, Write, Edit, Glob

Forge a complete Claude Code skill from a GraphQL API. Introspects the schema (or reads a local SDL file), emits one slash command per top-level Query/Mutation, generates `types.ts` + `client.ts` (Workers-compatible, zero Node built-ins), and writes paired test scaffolds per `[[forge-with-test-scaffold-pattern]]`.

How to use

/forge-graphql-skill shopify https://mystore.myshopify.com/admin/api/2024-10/graphql.json --schema-introspection --auth-header "X-Shopify-Access-Token: shpat_xxx"
/forge-graphql-skill github https://api.github.com/graphql --schema-introspection --auth-header "Authorization: Bearer ghp_xxx"
/forge-graphql-skill contentful --schema-file ./schema.graphql

What gets generated

~/.agentskills/<name>-graphql/
  SKILL.md                        ← master skill file, all commands linked
  types.ts                        ← TypeScript types from GraphQL schema (Zod-validated at runtime boundaries)
  client.ts                       ← Workers-compatible typed GraphQL client (graphql-request pattern, zero Node built-ins)
  commands/
    query-<QueryName>.md          ← one slash command per top-level Query field
    mutation-<MutationName>.md    ← one slash command per top-level Mutation field

tests/
  <name>-graphql/
    client.test.ts                ← Vitest unit tests (fetch-mocked) per [[forge-with-test-scaffold-pattern]]

e2e/graphql/
  <name>.spec.ts                  ← Playwright E2E smoke test against live endpoint (if HTTP-reachable)

Execution

ARGS="${ARGUMENTS}"
NAME="${ARGS%% *}"
REST="${ARGS#* }"

Step 1 — parse flags

ENDPOINT=""
SCHEMA_FILE=""
AUTH_HEADER=""
INTROSPECT=0

while [[ -n "$REST" ]]; do
  TOKEN="${REST%% *}"
  REST="${REST#* }"
  [[ "$REST" == "$TOKEN" ]] && REST=""

  case "$TOKEN" in
    --schema-introspection) INTROSPECT=1 ;;
    --schema-file) SCHEMA_FILE="${REST%% *}"; REST="${REST#* }"; [[ "$REST" == "$SCHEMA_FILE" ]] && REST="" ;;
    --auth-header) AUTH_HEADER="${REST%% *}"; REST="${REST#* }"; [[ "$REST" == "$AUTH_HEADER" ]] && REST="" ;;
    http*) ENDPOINT="$TOKEN" ;;
  esac
done

echo "SKILL: $NAME  ENDPOINT: $ENDPOINT  INTROSPECT: $INTROSPECT  SCHEMA_FILE: $SCHEMA_FILE"

Step 2 — acquire schema

**If `--schema-introspection` (and ENDPOINT set):** POST the standard introspection query.

cat > /tmp/introspect-body.json <<'EOF'
{"query":"{ __schema { queryType { name } mutationType { name } types { kind name description fields(includeDeprecated:false) { name description args { name type { kind name ofType { kind name ofType { kind name } } } } type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } inputFields { name type { kind name ofType { kind name } } } } } }"}
EOF

if [ -n "$AUTH_HEADER" ]; then
  curl -s -X POST "$ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "$AUTH_HEADER" \
    -d @/tmp/introspect-body.json > /tmp/gql-schema.json
else
  curl -s -X POST "$ENDPOINT" \
    -H "Content-Type: application/json" \
    -d @/tmp/introspect-body.json > /tmp/gql-schema.json
fi

# Verify introspection succeeded
node -e "const s=JSON.parse(require('fs').readFileSync('/tmp/gql-schema.json'));if(s.errors){console.error('Introspection failed:',JSON.stringify(s.errors));process.exit(1)}; console.log('Schema types:', s.data.__schema.types.length)"

**If `--schema-file`:** read the SDL file, parse it with `graphql` npm package or inline SDL parser.

if [ -n "$SCHEMA_FILE" ]; then
  cp "$SCHEMA_FILE" /tmp/gql-schema-sdl.graphql
  echo "Using local schema: $SCHEMA_FILE"
fi

Step 3 — extract top-level operations

node - <<'EOF'
const schema = JSON.parse(require('fs').readFileSync('/tmp/gql-schema.json', 'utf8'));
const types = schema.data.__schema.types;

const queryType = types.find(t => t.name === 'Query');
const mutationType = types.find(t => t.name === 'Mutation');

const queries = (queryType?.fields ?? []).map(f => ({ name: f.name, kind: 'Query', description: f.description, args: f.args, returnType: f.type }));
const mutations = (mutationType?.fields ?? []).map(f => ({ name: f.name, kind: 'Mutation', description: f.description, args: f.args, returnType: f.type }));

require('fs').writeFileSync('/tmp/gql-operations.json', JSON.stringify({ queries, mutations }, null, 2));
console.log(`Queries: ${queries.length}  Mutations: ${mutations.length}`);
queries.forEach(q => console.log('  Q:', q.name));
mutations.forEach(m => console.log('  M:', m.name));
EOF

Step 4 — create output directory

mkdir -p ~/.agentskills/${NAME}-graphql/commands
mkdir -p tests/${NAME}-graphql
mkdir -p e2e/graphql
echo "Output dir: ~/.agentskills/${NAME}-graphql"

Step 5 — write `types.ts`

Write `~/.agentskills/<name>-graphql/types.ts` as a **separate Write call**. Content:

// AUTO-GENERATED by /forge-graphql-skill — do not hand-edit; re-forge to update
// GraphQL skill: <name>  Source: <endpoint or schema-file>

import { z } from 'zod'

// ── Scalar base types ────────────────────────────────────────────────────────
export const GraphQLID = z.string()
export const GraphQLString = z.string()
export const GraphQLInt = z.number().int()
export const GraphQLFloat = z.number()
export const GraphQLBoolean = z.boolean()

// ── Generated object types (from schema introspection) ───────────────────────
// <EMIT ONE z.object() per non-scalar, non-builtin type found in __schema.types>
// Example shape (replace with actual schema types):
export const PageInfoSchema = z.object({
  hasNextPage: z.boolean(),
  hasPreviousPage: z.boolean(),
  startCursor: z.string().nullable(),
  endCursor: z.string().nullable(),
})
export type PageInfo