Skip to main content
skill CX Codex

graphos-factory — Claude Code skill: build Apollo Connectors from REST APIs

graphos-factory — a skill that turns REST APIs into GraphQL subgraphs for Apollo GraphOS. Maintains a git workspace with API inventory, operation selection, decision log and verification layers.

MIT 278 installs ★ 135 updated 2026-11-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add apollographql/skills --skill graphos-factory -a claude-code
Open on GitHub

What graphos-factory does

The skill generates an Apollo Connectors subgraph from a REST API, with or without an OpenAPI spec. It operates through a workspace: inventory.json holds the source API structure, selection.yaml lists chosen operations and fields, <name>.graphql is the subgraph schema. Every decision is recorded in decisions.json, verification facts in findings.json, working context in memory.md. The schema is edited incrementally: the skill computes the delta and changes only affected fragments, preserving hand edits.

It supports {{BASE_URL}} and {{AUTH_EXPR}} placeholders; local test values go in template.yaml, production values are rendered via export. Federation allows @key, @shareable, @requires, @provides, @external, @inaccessible, @listSize, @cost, @tag directives. The @tag directive is applied only when the supergraph uses GraphOS Contracts, with names from existing contracts.

Before first use, run bash <skill>/scripts/bootstrap.sh (downloads ~3 MB into ~/.cache/graphos-factory-core/), then . <skill>/scripts/env.sh to add graphos-factory and rover to PATH. Requires macOS, Linux or WSL with bash, curl, git, jq; end-to-end layers need Java 17+.

What it helps with

  • wrap a REST API as a GraphQL subgraph for Apollo GraphOS
  • preserve decision history and hand edits when evolving the schema
  • add or remove operations and fields from an existing connector
  • refresh a subgraph against a new OpenAPI spec
  • record live API traffic as test fixtures

Example prompts for the agent

  • Build a subgraph from the REST API using openapi.yaml
  • Add the getUser operation to the existing subgraph
  • Update the subgraph schema from the new OpenAPI version

How to install graphos-factory

1Skills CLI (Vercel)

npx skills add apollographql/skills --skill graphos-factory -a claude-code

2Manually: put the files in place

~/.claude/skills/graphos-factory/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/graphos-factory/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about graphos-factory

How do I install graphos-factory in Claude Code?

Run npx skills add apollographql/skills --skill graphos-factory -a claude-code, then open ~/.claude/skills/graphos-factory/SKILL.md. Before first use, run bash <skill>/scripts/bootstrap.sh and . <skill>/scripts/env.sh.

What does graphos-factory do?

The skill generates an Apollo Connectors subgraph from a REST API for a GraphOS supergraph. It maintains a workspace with API inventory, operation selection, decision log and verification layers. The schema is edited incrementally, hand edits are preserved.

Which Federation directives does graphos-factory support?

The schema may import @key, @shareable, @requires, @provides, @external, @inaccessible, @listSize, @cost and @tag. The @tag directive is applied only when the supergraph uses GraphOS Contracts, with names from existing contracts.

Source text

SKILL.md · MIT
---
name: graphos-factory
description: Build and iterate on an Apollo Connectors subgraph for a GraphOS supergraph from a REST API, with or without an OpenAPI or Swagger spec, in a dedicated git workspace that records what the API offers, the user's operation and field selection, every design decision, and the evidence each verification layer produced. Use whenever the user wants to wrap a REST API as a GraphQL subgraph for their supergraph, add or remove operations or fields from an existing connector subgraph, refresh one against a new spec, or record live API traffic as test fixtures, even if they do not say "connector", "subgraph" or "Apollo".
license: MIT
compatibility: macOS or Linux (WSL on Windows) with bash, curl, git and jq; Java 17+ for the end-to-end and live layers. Any Agent Skills host (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and others) that can run shell commands.
metadata:
  version: "0.12.3"
---

# graphos-factory

You turn a REST API into an Apollo Connectors **subgraph** for the user's
GraphOS supergraph, and keep it maintainable. The subgraph is the
deliverable: a schema the user composes with their other subgraphs.
**You are the generator**: no tool writes the schema for you. The `graphos-factory`
binary (the shared references write `graphos-factory-core <command>`; here that is
`graphos-factory`, installed beside it as the same binary) and the shell wrappers under
`graphos-factory-core/scripts/` do the mechanical work — reading a source into an inventory,
rendering placeholders, running rover, checking the invariants — and make no design
decisions at all.

**Source kinds.** `workspace.yaml`'s `source_kind` names the source. Only
`rest` is built: a REST API wrapped with Apollo Connectors, with or without
an OpenAPI document. gRPC / protobuf, databases and existing GraphQL APIs are
planned, not built: if a user asks for one, say so plainly and stop — never
approximate one with the REST path. The workspace contract is
source-agnostic; each kind adds its own intake reference and key grammar.

Everything durable lives in the **workspace**, a git repo you create per
subgraph: `inventory.json` is what the source offers, `selection.yaml` is
what the user chose, `<name>.graphql` is the subgraph schema the engineer
edits, the decision log (the calls, each with its alternatives:
`decisions.json`, then one file per decision under `decisions/`, written only
via `graphos-factory decisions`), the findings log (settled facts, likewise, via
`graphos-factory findings`) and `memory.md` are what you and your predecessors
learned. Read
[`workspace-contract.md`](graphos-factory-core/references/workspace-contract.md) once for the full
layout. The core's references are in `graphos-factory-core/references/`, this target's in `references/`.

**Never regenerate the schema wholesale after the first commit.** Compute the
delta and edit only what changed. Losing hand edits to a regeneration is the
specific failure this skill exists to avoid — and a hand edit you have not
codified (see "Hand edits" below) blocks an `apply` until you have.

**This target's contract** is the subgraph's place in the user's supergraph;
what the references leave open is listed under their "Open" headings. What
holds today, enforced by the binary: `{{BASE_URL}}` and `{{AUTH_EXPR}}` are the
only placeholders, with the scheme prefix *outside* the placeholder, and
`template.yaml` gives each a local test value (`export` renders them with the
production values, [`export-graphos.md`](references/export-graphos.md)); the Federation
directives the schema may import are `@key`, `@shareable`, `@requires`, `@provides`,
`@external`, `@inaccessible`, `@listSize`, `@cost` and `@tag`
([`federation-subgraph.md`](references/federation-subgraph.md)); one `@source` is the shape the
layers model, and a second is a lint warning (unmodelled, not forbidden); a type another subgraph owns keeps its owner's exact name, unprefixed, only once the user's resolved decision declares it (`decisions add --foreign-type NAME`, federation-subgraph.md § Entities another subgraph owns). **`@tag` is
for GraphOS Contracts, and off by default**: apply it only when the user's supergraph
uses contracts, with the names their contracts already filter on, recorded as a
decision. Never invent a tag; this target imposes no tag names, so `unknown-tag` never fires.

**Setup, before the first command.** `<skill>` below is the directory that holds this file. Whatever installed it (`npx skills add`, `gh skill install`, a Claude Code plugin, a copied directory) and whatever the agent (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI or any other), check with `bash <skill>/scripts/bootstrap.sh --check`, and on exit 127 run `bash <skill>/scripts/bootstrap.sh` once (about 3 MB into `~/.cache/graphos-factory-core/`); a session-start hook that already did it (`scripts/session-start.sh`, in a clone used as a plugin) makes the check pass. Then run `. <skill>/scripts/env.sh` in your shell, or at the start of every command when your shell keeps no state between commands: it puts `graphos-factory`, its `graphos-factory-core` link and rover on `PATH` and sets `GRAPHOS_FACTORY_CORE_SCRIPTS` (the `$S` below). The toolchain (`toolchain.sh`) is installed only once the user agrees, whatever the host. **First subgraph in a new workspace:** follow [`first-subgraph.md`](references/first-subgraph.md), the steps from `init` to `export` in order, each with its commands, its checks and the expected non-zero exits.

<!-- core:begin -->
## Before anything else

1. If a workspace exists, read the decision log (`graphos-factory-core decisions list .`,
   including `--open` for questions still awaiting the user), the findings
   (`graphos-factory-core findings list .`) and `.factory/memory.md` **in full**. Do not re-open a
   `resolved` decision unless the user asks. When they want to revise an answer to the
   same question, `graphos-factory-core decisions reopen . --id D-id` clears it and puts the record
   back to `open`, then settle it again with `decisions resolve`; when the question
   itself has changed, record a new decision instead. Never edit a record in place — the
   file is written only through that command. If the workspace still carries a legacy
   `.factory/decisions.md` and no `decisions.json`, run `graphos-factory-core decisions migrate .`
   once to import it (it preserves the `D-nnnn` ids and removes the `.md`), then
   continue. A `decisions.json` in the older format (provenance records titled `Hand
   edit codified:` or `Source patch:`, prose with no alternative) is split once with
   `graphos-factory-core decisions migrate . --split`: sort each record it lists by the test under
   "Write it down", then run it with `--sorted` (workspace-contract.md § `decisions.json`).
2. Read the target's contract (named above and under References) and
   `naming.md`. Violating them breaks the schema a router can run
   rather than a test: the target's `@source` and placeholder rules, and
   `{Service}_Type` / `{service}_field` with snake_case for multi-word names.
3. For new intake or before `select` / `apply`, make the cheap call first: does the
   user want customer-/tenant-specific fields the spec does not define (analytics
   fields, CRM custom objects, CMS content types)? If not, it is a generic wrapper —
   record `context_mode: generic` in `workspace.yaml` and move on (an unrecorded mode
   also reads as generic, so nothing blocks on it); a `modelId` argument or a JSON field
   alone does not make it specialized, and no `context.yaml` is needed. Do not ask for a
   tenant model, metadata export or credential merely because the endpoint accepts an
   identifier or JSON. Only if it is specialized or you are unsure, read
   `customer-context.md` (under References) and assess there — record `context_mode`
   and any dependencies before authoring.
4. Pick the verb the user needs (the target's verbs, `init` among them, follow
   this table) and read the reference it names.

## Verbs

| Verb | Read first | What you do |
|---|---|---|
| `discover` | spec-intake **or** api-discovery | build/refresh `inventory.json`; assess customer context and update its records/snapshots within the authorized scope; report the diff; never edit schema or selection |
| `select` | naming, schema-authoring | agree operations, roots, names, field exclusions, tags, pagination; surface every `[read?]` POST and confirm with the user which are reads before giving one `root: query`; write `selection.yaml` (each included operation with `include: true` and its `graphql` root and name — nothing writes this file for you); then `graphos-factory-core selection draft` proposes a `response.envelope` per included operation — **confirm each one with the user** and set `confirmed: true`, because a draft nobody agreed to must never become the schema's shape; it also drafts one `links:` entry per `candidate_entity_link` fact (`graphos-factory-core inventory links .` lists them) — **confirm each link with the user too** (`confirmed: true`, or `include: false` with a `reason`), because a relationship field is one request per parent and only the authored schema knows whether it would be circular; record each design question as a decision — `graphos-factory-core decisions add . --title T --question Q --choice LABEL … [--multiple]` (choices are numbered 1, 2, 3…; ids are kept only when every `--choice` is `id:label`) — and settle each with the user via `graphos-factory-core decisions resolve . --id D-id --chosen N --note …`, never as loose chat messages; record what the references settle for you as a finding (`graphos-factory-core findings add . … --cites REF`) when an instrument needs it, and otherwise do not record it; to revise a settled answer, `graphos-factory-core decisions reopen . --id D-id` and resolve it again. |
| `apply` | schema-authoring, mapping-language, testing | `graphos-factory-core lock --check` (stop on uncodified hand edits; the provenance drift it lists is not a stop); `graphos-factory-core context check` (resolve build gaps before authoring); `graphos-factory-core reconcile --baseline HEAD` names the delta (on a first apply the schema is not in HEAD yet, and every span reads as `added`); edit the schema for exactly those spans, keeping every override's assertions true; for each confirmed link, `graphos-factory-core links apply . --dry-run` prints the field-level `@connect` keyed by `$this` (no `@key`; no header and no argument unless the by-id root field carries a per-call credential, which it mirrors — same argument, same header or query parameter; for a nullable fk, the `isSuccess` and selection null guards, because the router still sends `GET …/` for a null parent) to paste into the host type — it refuses `circular`, `self`, `no-fk-field`, `field-exists`, `nullable-fk`, `no-host`, `no-root-field` and `target-refused` (a stale entry whose keep-or-drop decision is not resolved `keep`) (connectors-language § Relationship fields) and exits 1 whenever any entry is refused, even with others printed; `graphos-factory-core scaffold` drafts the case, stub and unit entry of every operation that has none (the notes say what the unit entry could not carry) — audit every placeholder, then `e2e.sh --generate`; run it again (clean; `changed since HEAD` ⊆ the delta); `graphos-factory-core source-coverage . OP-KEY --check` on every operation you touched, and `graphos-factory-core source-coverage . --check` (no OP-KEY: every selected operation, each failing one named) before `lock` — zero `unaccounted` and zero `unresolved` in both directions, and no `unaccounted` behaviour row (an optional argument's doc comment must carry the source's omission sentence, or a `behaviour` omit says why not — a finding's `not-applicable`, a decision's `editorial`), is the bar (`--check` fails closed); each path you meant to leave off is recorded, not a silence: one you chose not to expose is a decision whose alternative is exposing it, `graphos-factory-core decisions add . --title T --question Q --choice omit:L --choice expose:L --resolved --chosen omit --note WHY --omit 'op\|direction\|path\|editorial'`, and one an expression consumes is a finding, `graphos-factory-core findings add . --title T --body TEXT --cites REF --omit 'op\|direction\|path\|consumed'` (quote each and type plain pipes: each backslash here is only this table's escape; `findings add` refuses `editorial`); an `unresolved` row from the classifier's own grammar (a request `->map(…)->first`, a request-side `->match`, a chained method such as `->match->first`) (or a `...` spread that is not the `disc->match(…)` abstract-type form) is recorded and reported as not verified by this layer, never cleared by editing `inventory.json` (schema-authoring.md § Coverage); `graphos-factory-core lock`; validate; commit `apply:` |
| `codify` | workspace-contract, mapping-language | a hand edit **to the schema** was detected: learn why from the engineer or the diff, then `graphos-factory-core codify --key K --reason R` with `--expressed` (after moving the intent into `selection.yaml`) or `--assert kind=value`…, and `--context TEXT` for the why the diff cannot show (codify records no decision); for an edit to a pinned spec, `graphos-factory-core codify --source PATH --reason R`, then, in a spec-backed workspace, rebuild the inventory (`graphos-factory-core inventory build PATH`; an `intake: mixed` workspace re-runs `infer --update-inventory` after it) so the correction and its patch marks reach `inventory.json`, and re-run `reconcile`; commit `decide:`. `--key` refuses a span that is in sync with the lock: a correction to something the tool *inferred* is not a hand edit — see the first policy below |
| `validate` | testing, customer-context | check context with `--phase live` before live requests; report live-only gaps as `not_run` without blocking offline layers; compose → unit → e2e → write-body proof → conformance → lint → json-accounting → live (the write-body proof and json-accounting layers are non-gating: a `fail` is printed as open findings, never as a pass; `evidence/latest.json` is `contract_version: 2`); write `evidence/latest.json`; report skipped layers as skipped; a unit run with zero cases is `not_run`, never a pass; every suite with zero cases fails unless its header's first sentence cites its decision (`D-0019` or `D-k7m2qx`), and a `skip: true` case fails; every selected operation is a live case or a live `exclusions:` entry with its reason; lint's `link-untested` warns on each relationship field that no unit entry targets (`<Type>.<field>`) or no e2e case selects, and evidence's report names each one; `link-null-untested` warns when a nullable fk has no null-parent e2e case (a mapping for the empty-segment GET serving a case that selects the field), and, when `tests/live.yaml` exists, `link-live-unaccounted` when no live case selects the field and no `exclusions:` entry `field: "<Type>.<field>"` names it; a field with neither unit nor e2e, with no null-parent case, or excluded live is not validated; say so (scaffold does not draft link-field tests yet: write the unit entry and e2e case by hand, connectors-language § Relationship fields); a conformance body the oracle could not judge is `unchecked` (no documented shape) or `unmatched` (no such operation, unreadable body — this one fails), never a pass; an accepted gap is `graphos-factory-core codify --waive TARGET --status S --reason R`; before reporting, `graphos-factory-core lock --check --provenance`; when it exits 3, relock (`graphos-factory-core lock`) only when a plain `graphos-factory-core lock --check` reports no changed or unattributed span, pinned-source problem or edited inventory (it then prints the relock advice, and `--json` sets `relock_advisable`) — the drift is provenance alone (a case, a stub, a `memory.md` line), or a document `sources.lock.yaml` no longer pins, which a relock stops watching on purpose. Otherwise the schema, a pinned document or `inventory.json` changed under the lock: stop and follow "Hand edits" (codify a span or pinned source, rebuild an edited inventory), because a relock would erase the only record of the edit |
| `record <op>…` | api-discovery, testing | `graphos-factory-core probe` each request (GET only unless told otherwise; scrubbed before it touches disk); `graphos-factory-core infer --update-inventory` for the oracle; `graphos-factory-core fixtures` for the stubs; note spec-vs-reality findings in `memory.md` |
<!-- core:end -->

This target's verbs, `init` first (it records the target, `skill.name: graphos-factory`; `--target` is optional):

| Verb | Read first | What you do |
|---|---|---|
| `init <name>` | workspace-contract | decide the subgraph name (snake_case or kebab-case, naming.md) and `context_mode` (step 3 above), fetch the description document yourself, then `graphos-factory init <dir> --name N --spec FILE [--url U] --context-mode generic\|specialized` — it writes `.factory/workspace.yaml` (`skill.name: graphos-factory`), the working copy and its pinned vendor copy, `sources.lock.yaml` and `inventory.json` exactly as `sources pin` + `inventory build` would, plus four skeletons: `<directory>.graphql` (the spec links and the one `@source`, no root field, so compose fails until the first apply), `template.yaml` (`BASE_URL` = the document's first absolute server, else a local stand-in its comment asks you to complete; `AUTH_EXPR` = `{$env.<SERVICE>_TOKEN}` with the scheme named; local test values only, never the production host, which is given at export), `supergraph.yaml` (rover's compose config for this one subgraph, not the user's supergraph) and `tests/router.yaml` (the e2e `override_url`); act on every comment in them, and one that already exists is left alone. It refuses a directory that already holds a workspace; `--dry-run --json` lists every file's path, content and sha256 without writing. It never runs git: **standalone**, `git init` the directory; **already inside a repo** (a monorepo, one folder per subgraph), let the enclosing repo track `<name>/` and do not nest a second repo. Then commit. A no-spec workspace (`intake: discovered`) has no document to pin: write `workspace.yaml` (with `skill.name: graphos-factory`) and `sources.lock.yaml` by hand, as workspace-contract shows |
| `export` | export-graphos | only after `validate`: `graphos-factory export . --out DIR --base-url URL` (DIR outside the workspace; URL the production host, which the user gives you) renders `DIR/<directory>.graphql` and prints the rover commands, the router's credential variables and minimums, and what is not verified. It refuses an unvalidated workspace (no evidence, a file the layers read changed since `evidence` ran, which it names, a layer not `pass`, an operation with no executed evidence, a lint error) and a base URL that is not an absolute http(s) URL, carries userinfo or is local, and says why, in `evidence`'s terms: fix that (then `evidence`) and re-run, never work around it. It also refuses a `supergraph_check` that ran and failed, naming rover's errors. Hand the user its output. Never run `rover subgraph check` or `publish` by hand, never handle, ask for or print a GraphOS key, and report `supergraph_check` (when not `pass`) and anything else it lists as not verified |

`validate` on this target also runs its evidence layer, `supergraph_check`: `rover subgraph check` against the user's
published variant, only with `APOLLO_KEY` in their environment (the key is theirs: never ask for, set or print it) and a graph ref:
ask once per session which `<graph>@<variant>`, then set `GRAPHOS_FACTORY_GRAPH_REF` on the commands you run; their own
`GRAPHOS_FACTORY_SUPERGRAPH_CHECK=auto` uses `$APOLLO_GRAPH_REF` (never set it for them). Else `not_run` (references/verification.md). The compose layer composes the subgraph alone. Report a `not_run` or `skipped`
check as not run, never as a pass, and say plainly the subgraph has not been checked against the user's supergraph.

<!-- core:begin -->
## Instruments

One binary, the product's, plus the shell wrappers in `graphos-factory-core/scripts/` around rover, Java
and curl for the validation layers. It is downloaded from the skill's GitHub releases (the rolling
`edge` pre-release until a versioned release exists) by the skill's own `scripts/bootstrap.sh` (the
product's session-start hook may run it; otherwise run it yourself), which also links it as `graphos-factory-core`; it is built from
`crate/` only when developing the skill itself (`bootstrap.sh --build`). Every wrapper takes
the binary from `$GRAPHOS_FACTORY_CORE_BIN`, then that link in the bootstrap cache, then PATH, prints which
one and its version to stderr, and exits **78** (a `fail`, never a skip) when it is
older than the pin (`crate/Cargo.toml`, an installed skill's `release.env`, or `$GRAPHOS_FACTORY_CORE_VERSION`); `evidence` hands the
wrappers its own binary. On 78, re-run `bootstrap.sh` (`--build` in a checkout) or set
`GRAPHOS_FACTORY_CORE_BIN` — never lower the pin to get past it. Run everything from the workspace
root. `graphos-factory-core <command> [verb] --help` (or `-h`) prints that command's usage and reads
or writes nothing. A flag the verb does not declare — a typo, or two flags
quoted into one argument — is refused with exit 2 and nothing runs; fix the
spelling, never drop the flag. `rover` is needed for compose, unit, e2e and live; Java for
e2e's WireMock; nothing is ever installed into a workspace. rover's composition plugin is under the Elastic License v2, which only the user accepts, by setting `APOLLO_ELV2_LICENSE=accept`: until then those four layers are `not_run`. Ask once: show the link, and only on an explicit yes set `APOLLO_ELV2_LICENSE=accept` for the commands you run this session (record the consent in memory.md); never set it unasked, and tell them `export` in their shell profile makes it permanent.

```bash
S=path/to/graphos-factory-core/scripts
export GRAPHOS_FACTORY_CORE_SCRIPTS=$S                    # evidence needs to find the wrappers
# If the host supplies a model identifier, set GRAPHOS_FACTORY_CORE_LLM_MODEL to that exact value.
# Never infer or guess a model identifier. The lock records unknown when this value is absent,
# and `lock` prints a one-line warning for that and for a skill source of binary-build.

graphos-factory-core inventory build openapi.json          # description document (OpenAPI 3.x or Swagger 2.0) -> .factory/inventory.json (refuses to overwrite a hand-edited one)
graphos-factory-core inventory list --tag Incidents        # page the inventory, grouped by tag; 50 a page. --json: total, offset, limit, next_offset (null on the last page) — a loop over every operation follows next_offset
graphos-factory-core inventory list --support needs_review # what still needs a decision
graphos-factory-core inventory describe get:/v2/incidents  # one operation, shapes expanded
graphos-factory-core inventory links . [--json]            # every candidate_entity_link fact flat: shape, property path (album_id / []>album_id / songs[]>album_id), the canonical GET-by-id operation, whether the host is a list item and whether that operation is selected, then every GET-by-id refused as a target because its response does not carry its key — a hint, never a finding; judge each and record the call with `graphos-factory-core decisions add`
graphos-factory-core inventory diff old.json new.json      # what a spec refresh changed

graphos-factory-core context check . [--phase build|live] [--json]   # declared customer requirements; exit 2 for missing context, 1 for invalid records
graphos-factory-core context capture . (--requirement ID|--input) --id ID --from FILE --representation raw|derived|transcribed …   # copy one local non-secret artifact and record its provenance
graphos-factory-core decisions list . [--open] [--causal] [--json]    # the decision log: decisions only — calls with their alternatives, resolved, and open questions awaiting the user. The records of `.factory/decisions.json` (numbered `D-nnnn`, never added to), then one file per record added since under `.factory/decisions/` (random `D-k7m2qx`); --causal orders by after/amends and shared affects, a `via:` line per edge
graphos-factory-core decisions add . --title T [--question Q] [--choice LABEL]… [--multiple] [--phase P] [--affects PATH]… [--resolved --chosen N --note TEXT --decision TEXT --by user|agent] [--omit 'operation|direction|path|reason']… (a resolved request omit also removes an optional source body member from the write-body proof; a member the source requires stays a gap, `required_member_omitted`, and `decisions add` warns when an omit targets one) [--json-reason 'Type.field|reason']… [--null-handling 'operation|argument|behavior']… [--secret-field 'Type.field|disposition|reason']… [--foreign-type NAME]… [--slug S] [--after D-id]… [--amends D-id]…   # record a decision, as its own file with a random id, printing `N  label` per choice (choices numbered 1, 2, 3… in flag order; ids are kept only when every `--choice` is `id:label`, else each value is a whole label; a duplicate id, or an invalid one when every value looks like `id:label`, is refused at the flag) (--after names decisions it presumes, --amends ones whose answer it changes where their affects overlap): an open question, or with --resolved a call already made (`resolution.by` defaults to agent; --note says why you did not ask); refuses, exit 1 `no-alternative`, a record that names its alternative none of three ways — a --question, two or more --choice, or an --omit with reason `editorial` — a settled fact is `findings add`; --omit records a structured scope exclusion `source-coverage` reads, only on a resolved record, and an `editorial` omit lives only here; path `.` omits the whole direction for that operation, which is how to record an EmptyResponse 204's empty root row; --json-reason records why a response field is left typed as the workspace's JSON scalar, from `crate::json_accounting::REASONS`, read only on a resolved record — never a selection.yaml field or a schema doc comment; --null-handling records what the connector sends for an explicit null argument (behavior: send_null or omit), read only on a resolved record; --secret-field records a reviewed credential-shaped response field (disposition expose or exclude) that lint's secret-field-exposed rule reads, only on a resolved record; --foreign-type declares a type another subgraph owns, which the schema may then declare under its owner's exact name, read only on a resolved record and only by a target that allows it (that target's references say where); direction `behaviour` waives an omission sentence an argument's doc comment leaves out, path `query:NAME`/`path:NAME`/`header:NAME`/`body:KEY.PATH`, reason `editorial` or `not-applicable`
graphos-factory-core decisions resolve . --id D-id [--chosen N|LABEL]… [--note TEXT] [--decision TEXT] [--by user|agent] [--force]   # settle an open decision (with --force it replaces the whole resolution: pass the old --decision and the old note plus what you add, to amend a record without losing it); the same command a headless agent and a host UI both use
graphos-factory-core decisions reopen . --id D-id [--json]   # revise a decision: clear a resolved/superseded record's resolution and set it back to open (everything else kept); refuses an unknown id, an open record, or a missing/invalid log
graphos-factory-core decisions supersede . --id D-id [--json]   # mark a resolved decision replaced: status only, its answer kept; it stops counting as resolved everywhere (its omits, json_reasons and null_handling, its affects, a links: decision: naming it), so re-record what still applies; the fix for lint's `stale-omit` (a finding's: `findings supersede`)
graphos-factory-core decisions link . --id D-id (--after D-id | --amends D-id)… [--json]   # edges on a decision recorded as its own file, the fix for lint's `decision-overlap`; an old D-nnnn record never gains a field, so put the edge on the newer record
graphos-factory-core decisions migrate . [--keep-md] [--force] [--dry-run] [--json]   # one-time: import a legacy .factory/decisions.md into decisions.json (preserves D-nnnn ids, parses fenced Omits: blocks into structured omits), then remove the .md
graphos-factory-core decisions migrate . --split [--sorted FILE] [--dry-run] [--json]   # one-time, an older-format log (FILE: YAML/JSON mapping each listed D-nnnn to `{as: decision, question, choices, chosen, by, note}` | `{as: finding, cites, body, …}` | `{as: memory, line}` | `{as: drop}`; without it the unassigned records are listed and nothing is written, exit 1 `unsorted`): codify records move onto the override, waiver or patch they shadow, refresh records become findings, a record with a question, choices or an editorial omit stays a decision; lists every other record for you to sort by hand and refuses to write without --sorted until each is assigned
graphos-factory-core findings list . [--json]             # the findings log (`.factory/findings.json`, then one file per finding added since under `.factory/findings/`): facts a reference or the wire settled, `F-nnnn` or random `F-9k2wde`, current until superseded; every omits/affects reader takes these with the resolved decisions
graphos-factory-core findings add . --title T --body TEXT [--cites REF] [--source agent|codify|sources] [--affects PATH]… [--omit 'operation|direction|path|reason']… [--evidence E]… [--related D-id|F-id]…   # record a fact an instrument needs, or the next session does; omit reason `consumed` or `not-applicable` — refuses `editorial`, which is a decision
graphos-factory-core findings supersede . --id F-id       # a later finding replaces it; it stops counting
graphos-factory-core source-coverage . [OP-KEY] [--json] [--check]   # source coverage: every fact the source offers is covered by the schema, or a resol...

© apollographql · MIT · apollographql/skills

Similar skills

All skills for Backend and APIs →

From the same set13

The whole set →
apollo-server Guides AI agents in building GraphQL APIs with Apollo Server 5.x. Useful when setting up schemas, writing resolvers, and configuring authentication. CX Codex +1 3,300installs apollo-connectors apollo-connectors walks an agent through wiring a REST API into a GraphQL supergraph with @source and @connect. Best for quick edits to an existing Connectors schema. CX Codex +1 2,300installs apollo-federation Guides an agent through Apollo Federation subgraph schemas: directives, entities with @key, composition errors. Handy when a supergraph spans several GraphQL services. CX Codex +1 2,100installs apollo-router Writes version-correct router.yaml for Apollo Router v1.x and v2.x and flags the sections where the two schemas diverge. CX Codex +1 2,000installs apollo-kotlin Walks the agent through Apollo Kotlin setup in a Gradle project: schema, codegen, an ApolloClient with auth and cache, plus operations. CX Codex +1 1,900installs apollo-router-plugin-creator apollo-router-plugin-creator helps build native Rust plugins for Apollo Router. It assists with request lifecycle hooks and modifying existing router extensions. CX Codex +1 1,800installs apollo-ios Walks your agent through adding Apollo iOS to a Swift project: codegen config, client setup, queries, subscriptions and mock-based tests. CX Codex +1 1,300installs apollo-skills Skills that teach Claude the Apollo GraphQL stack: client, server, federation, connectors, Rover and the MCP server. Useful when your agent touches GraphQL code. ★ 135repo stars

Project sponsors

Companies that keep this analytics open