Create a Connector

Use this skill when adding a provider or extending its declarative capabilities. For consumption/setup only, use the connector guide.

Load the contract, not a catalog

Read the connector specification 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 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.

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:

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 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, explicit effect scope, and exact reviewed published revision. Stop on authorization denial.