Create Connector

---
name: create-connector
description: Create or extend a declaration-only third-party connector, with narrow reads, separate safe outputs, optional protected triggers, and offline conformance evidence.
---

# 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.