create-connector

# Create a Connector Use this skill when adding a provider or extending its declarative capabilities. For consumption/setup only, use [the connector guide](../../aw/connectors.md). ## Load the contract, not a catalog Read the [connector specification](../../../docs/src/content/docs/specs/connector-specification.md) and only the closest declaration in `.github/workflows/connectors/`. Use its `docs` references and matching `connector-documentation` XML, not a product name, old native handler, or guessed OAuth scope as API evidence. Read the [authoring guide](../../aw/connectors.md#author-or-extend-a-declaration) for advanced policies. No remote skill discovery is needed. Confirm one useful consumer scenario, exact authorized resources, needed read evidence, desired effect, credential route, and any trigger evidence. If the provider's API or authorization details are unavailable, mark that capability unsupported instead of inventing an endpoint, scope, or tool. ## Create the smallest source Create `.github/workflows/connectors/<id>.md` with `connectors.<id>` and ordinary `import-schema`. Start from section 9 of the specification or the closest existing provider. Its synthetic API is an offline shape example, never a real provider or live-test target. | Need | Declare | | --- | --- | | Bounded REST/fixed GraphQL read | `tools.<read>` with exact `tool`, typed `inputs`, fixed request, minimal checked projection. | | Hosted streamable-HTTP MCP read | `mcp-servers.<registration>` with fixed URL, `readOnly: true`, exact native `tools` schemas and grants. | | Provider mutation | `safe-outputs.<operation>` with a distinct safe-output credential and exact resource checks. | | Native event | `triggers.<name>` with fixed `resourceOrigins`, verification profile, evidence predicates, normalization and grants; no ingress deployment. | | Resource content/context | A selected reader. Do not add public `context` or automatic hydration. | Set `experimental: true` for a new unproven contract. Add literal official HTTPS `docs` URLs actually consulted. Expose resource arrays and secret NAMES through `import-schema`; tokens never belong in `with`, source, or prompts. Describe every import binding and give resource arrays explicit string item types. Put declaration metadata, endpoints, credentials, resources, triggers, readers, hosted MCP registrations, and safe outputs in that order. Put input type/required before its constraints. Reuse provider-local anchors for identical primitive schemas without combining independent grants or credential phases. Preserve quoted import substitutions and define anchors before their aliases. Keep merge keys before explicit overrides and verify nested aliases with the actual compiler and bundled runtime, not only a generic YAML parser. Use `token`, scoped `github-app`, or audience-bound `github-oidc` only when that route is valid for the actual provider. Neither GitHub route exchanges tokens. Bound every string and response. Request placeholders take safe individual segments. New local readers use kebab-case selectors and unprefixed snake_case `tool` names; preserve existing advertised names and exact hosted native MCP names rather than renaming them for style. Query/body values use `input`, `literal`, `object`, or `array`. Resource inputs are required strings checked against exact grants before secrets. Correlate the returned ID with the requested ID, not merely some allowed ID. Reject partial pages when completeness matters. Project only needed evidence. Mark human text with `sanitize: title/body`; use `body-plain` for literal API text or ADF text nodes so publisher markup is not sent as content. Both body formats retain protected attribution and sizing. Do not sanitize IDs as body text. Use `body-plain-compact` only for APIs whose documented representation collapses consecutive ASCII spaces and newlines, so exact echoed-text checks stay intact. Do not add per-provider runtime code, checkout/build/install hooks, dynamic URLs/queries/scripts, automatic pagination, arbitrary patches, credential fallbacks, or grants derived from responses. If the shared contract cannot express a required behavior, report the gap; extend reusable infrastructure only when the task explicitly includes that implementation. ## Supply a complete consumer and documentation Enclose the entire Markdown body in one XML/HTML comment containing a matching `connector-documentation` XML block with purpose, acquisition/renewal instructions, phase credential names/scopes, input/grant contracts, evidence/privacy limits, and complete consumer YAML/prompt elements. Never include secret values or double-hyphen sequences or nested comments. Do not embed Markdown frontmatter delimiters inside it or leave usage instructions outside the comment: the body is otherwise a system prompt. Full-source security scans still apply; do not add exemptions for documentation. Keep credential-format details in import input metadata and reference the inputs from the comment. Documentation is stripped from prompts, not executed as setup. Create a minimal consumer with normal `uses`/`with`, `workflow_dispatch`, explicit network approval, one reader and one `staged: true`, `max: 1` effect. For HTTP MCP prefer `{registration: [exactNativeTool]}` over the whole profile. Specimen grants must match in YAML and prompt. Say what the read does NOT prove and never claim staged delivery. Importing alone must select nothing. In this repository, add a source-only fixture to `pkg/cli/workflows/<id>-golden.md`, following the existing golden harness. Wire the new fixture into its provider scenario/CLI compilation matrix; do not install goldens under `.github/workflows/` or commit fixture lock files. Update the human connector reference with honest setup and evidence limits. ## Validate offline first Use a connector-capable compiler and the matching bundled runtime: ```bash gh aw connector <id> setup --file .github/workflows/connectors/<id>.md gh aw compile <consumer> --strict --no-emit gh aw connector <id> test --phase safe-output --capability <operation> \ --file .github/workflows/connectors/<id>.md \ --input 'resources=["approved-id"]' \ --args '{"resource-id":"approved-id","text":"Offline conformance example"}' \ --node-runtime actions/setup/js/connector_runtime.cjs ``` The last command is a shape illustration: replace input, argument, and operation names with the actual declaration's schema. `--input name=JSON` binds an import input; `--grant collection=JSON-array` replaces a declared resource grant. Annotated safe-output text requires the matching Node runtime and dependencies. Setup and safe-output tests read no credentials and perform no provider writes. An agent-phase test DOES contact the provider; do not run it as offline validation. Add tests for import-only/no capability, phase pruning, exact native selection, invalid arguments/grants before credentials, wrong response identity/types, staging with zero secret/HTTP accesses, publication bounds, and Go/Node parity. For supported triggers, add complete/nonmatching native fixtures and frozen predicate parity; projection must report `operational: false`. Check local/pinned imports, extracted XML examples, and deployment file closure. Run `make compile-cli-workflows` for the golden matrix and follow the [developer gates](../developer/SKILL.md) for code changes. Report source, scenario, exposed methods/effect, declared credential routes, offline evidence, and unsupported behavior. Do not claim consent, receiver enrollment, token validity, provider delivery, or useful output quality from a compile or mock. Live execution requires the [debugging gates](../../aw/debug-agentic-workflow.md), explicit effect scope, and exact reviewed published revision. Stop on authorization denial.