graphql-security — Agent Skill

An Agent Skill that helps agents write and review secure GraphQL client code — the code that sends queries and mutations to a GraphQL API.

Works with any agent that supports the open SKILL.md format, including Cursor, Claude Code, Codex, and 60+ more via the skills CLI.

The most common review failure: interpolating untrusted input into the query document instead of passing it through typed variables.

---

What it does

Your agent will automatically use this skill when you write or review code that calls GraphQL APIs:

• Injection prevention — pass dynamic values as variables, never interpolate into the query string
• Dynamic fields — allowlist field/sort/filter keys (variables cannot substitute identifiers)
• Auth & secrets — tokens via headers and secret stores, never hardcoded or logged
• Input validation — bound pagination, list sizes, enums, and IDs before send
• Error handling — don't leak errors[].message internals to users or logs
• Client hardening — timeouts, SSRF prevention, safe retry policies

Example prompts

Review this GraphQL query for security issues
Fix: we're interpolating user input into the gql template literal
How should I pass a search term to this Apollo query safely?
Is it OK to put the auth token in the GraphQL query string?

Example output

This query builds the document with `user(name: "${name}")`. If name contains " or }, it can break out of the intended structure. Pass name as a $name: String! variable instead.

---

Topics covered

Domain	Reference file	Covers
Injection	references/injection.md	Variables vs interpolation, dynamic fields, multi-stack examples
Auth & secrets	references/auth-secrets.md	Token storage, headers, HTTPS, log redaction
Input validation	references/input-validation.md	IDs, enums, pagination, lists, file uploads
Errors & logging	references/errors-logging.md	Safe error messages, PII scrubbing
Client hardening	references/hardening.md	Timeouts, SSRF, persisted queries, retries

---

Installation

Install with the skills CLI — it auto-detects your agents and symlinks the skill into the right directories:

npx skills add ikhattab/graphql-security

Common options:

# Install globally (available across all projects)
npx skills add ikhattab/graphql-security -g

# Install to specific agents
npx skills add ikhattab/graphql-security -a cursor -a claude-code

# Non-interactive (CI/CD friendly)
npx skills add ikhattab/graphql-security -g -a cursor -y

Use without installing:

npx skills use ikhattab/graphql-security@graphql-security | claude

Browse and discover skills at skills.sh.

Other install methods

Copy or symlink the skills/graphql-security folder into your agent's skills directory:

Agent	Personal (global)	Project-scoped
Cursor	~/.cursor/skills/graphql-security/	.cursor/skills/graphql-security/
Claude Code	~/.claude/skills/graphql-security/	.claude/skills/graphql-security/
Codex	~/.codex/skills/graphql-security/	.agents/skills/graphql-security/

Example (Cursor, global):

ln -s "$(pwd)/skills/graphql-security" ~/.cursor/skills/graphql-security

---

Common pitfalls this skill catches

• Template literal injection — gql`...${userInput}...` in query documents
• "It's just an ID" — IDs are strings; injectable characters break document structure
• Dynamic sort/filter keys — sortBy=${req.query.sort} is identifier injection
• Token in URL — ?token=... ends up in access logs and browser history
• Logging full requests — variables often contain PII and tokens
• Trusting GraphQL errors — errors[].message may expose SQL, paths, or stack traces
• Unbounded batch queries — user-supplied ID lists generating unlimited aliases

---

License

MIT — see LICENSE