graphql-schema
GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- graphql-schema
- risk
- critical
- source
- https://github.com/ChrisWiles/claude-code-showcase/tree/main/.claude/skills/graphql-schema
- license
- MIT
- date_added
- 1782864000000
- description
- GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.
- source_repo
- ChrisWiles/claude-code-showcase
- source_type
- community
- license_source
- https://github.com/ChrisWiles/claude-code-showcase/blob/main/LICENSE
03 SKILL.md 正文
GraphQL Schema Patterns
When to Use
Use this skill when you need graphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.
Core Rules
- NEVER inline
gqlliterals - Create.gqlfiles - ALWAYS run codegen after creating/modifying
.gqlfiles - ALWAYS add
onErrorhandler to mutations - Use generated hooks - Never write raw Apollo hooks
File Structure
src/
├── components/
│ └── ItemList/
│ ├── ItemList.tsx
│ ├── GetItems.gql # Query definition
│ └── GetItems.generated.ts # Auto-generated (don't edit)
└── graphql/
└── mutations/
└── CreateItem.gql # Shared mutations
Creating a Query
Step 1: Create .gql file
# src/components/ItemList/GetItems.gql
query GetItems($limit: Int, $offset: Int) {
items(limit: $limit, offset: $offset) {
id
name
description
createdAt
}
}
Step 2: Run codegen
npm run gql:typegen
Step 3: Import and use generated hook
import { useGetItemsQuery } from './GetItems.generated';
const ItemList = () => {
const { data, loading, error, refetch } = useGetItemsQuery({
variables: { limit: 20, offset: 0 },
});
if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingSkeleton />;
if (!data?.items.length) return <EmptyState />;
return <List items={data.items} />;
};
Creating a Mutation
Step 1: Create .gql file
# src/graphql/mutations/CreateItem.gql
mutation CreateItem($input: CreateItemInput!) {
createItem(input: $input) {
id
name
description
}
}
Step 2: Run codegen
npm run gql:typegen
Step 3: Use with REQUIRED error handling
import { useCreateItemMutation } from 'graphql/mutations/CreateItem.generated';
const CreateItemForm = () => {
const [createItem, { loading }] = useCreateItemMutation({
// Success handling
onCompleted: (data) => {
toast.success({ title: 'Item created' });
navigation.goBack();
},
// ERROR HANDLING IS REQUIRED
onError: (error) => {
console.error('createItem failed:', error);
toast.error({ title: 'Failed to create item' });
},
// Cache update
update: (cache, { data }) => {
if (data?.createItem) {
cache.modify({
fields: {
items: (existing = []) => [...existing, data.createItem],
},
});
}
},
});
return (
<Button
onPress={() => createItem({ variables: { input: formValues } })}
isDisabled={!isValid || loading}
isLoading={loading}
>
Create
</Button>
);
};
Mutation UI Requirements
CRITICAL: Every mutation trigger must:
- Be disabled during mutation - Prevent double-clicks
- Show loading state - Visual feedback
- Have onError handler - User knows it failed
- Show success feedback - User knows it worked
// CORRECT - Complete mutation pattern
const [submit, { loading }] = useSubmitMutation({
onError: (error) => {
console.error('submit failed:', error);
toast.error({ title: 'Save failed' });
},
onCompleted: () => {
toast.success({ title: 'Saved' });
},
});
<Button
onPress={handleSubmit}
isDisabled={!isValid || loading}
isLoading={loading}
>
Submit
</Button>
Query Options
Fetch Policies
| Policy | Use When |
|---|---|
cache-first |
Data rarely changes |
cache-and-network |
Want fast + fresh (default) |
network-only |
Always need latest |
no-cache |
Never cache (rare) |
Common Options
useGetItemsQuery({
variables: { id: itemId },
// Fetch strategy
fetchPolicy: 'cache-and-network',
// Re-render on network status changes
notifyOnNetworkStatusChange: true,
// Skip if condition not met
skip: !itemId,
// Poll for updates
pollInterval: 30000,
});
Optimistic Updates
For instant UI feedback:
const [toggleFavorite] = useToggleFavoriteMutation({
optimisticResponse: {
toggleFavorite: {
__typename: 'Item',
id: itemId,
isFavorite: !currentState,
},
},
onError: (error) => {
// Rollback happens automatically
console.error('toggleFavorite failed:', error);
toast.error({ title: 'Failed to update' });
},
});
When NOT to Use Optimistic Updates
- Operations that can fail validation
- Operations with server-generated values
- Destructive operations (delete)
- Operations affecting other users
Fragments
For reusable field selections:
# src/graphql/fragments/ItemFields.gql
fragment ItemFields on Item {
id
name
description
createdAt
updatedAt
}
Use in queries:
query GetItems {
items {
...ItemFields
}
}
Anti-Patterns
// WRONG - Inline gql
const GET_ITEMS = gql`
query GetItems { items { id } }
`;
// CORRECT - Use .gql file + generated hook
import { useGetItemsQuery } from './GetItems.generated';
// WRONG - No error handler
const [mutate] = useMutation(MUTATION);
// CORRECT - Always handle errors
const [mutate] = useMutation(MUTATION, {
onError: (error) => {
console.error('mutation failed:', error);
toast.error({ title: 'Operation failed' });
},
});
// WRONG - Button not disabled during mutation
<Button onPress={submit}>Submit</Button>
// CORRECT - Disabled and loading
<Button onPress={submit} isDisabled={loading} isLoading={loading}>
Submit
</Button>
Codegen Commands
# Generate types from .gql files
npm run gql:typegen
# Download schema + generate types
npm run sync-types
Integration with Other Skills
- react-ui-patterns: Loading/error/empty states for queries
- testing-patterns: Mock generated hooks in tests
- formik-patterns: Mutation submission patterns
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
04 同仓库更多 Skills
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
stop-slop
Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells and produce more human-like writing.
ogilvy-copywriting
Apply David Ogilvy's advertising principles when writing or reviewing copy, headlines, product descriptions, landing pages, ads, emails, or any persuasive text. Use when the goal is copy that sells, not copy that wins awards. Covers positioning, headlines, promises, brand voice, long-form copy, and visual logic. Source: How to Create Advertising That Sells (1972) + Ogilvy on Advertising.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.