coral-create-source-spec

Coral Create Source Spec

Use this skill when the task is to author or repair a Coral source spec.

Goal

Produce a valid, queryable Coral source spec that works with:

• coral source lint <path>
• coral source add --file <path>
• coral source test <name>
• coral sql
• coral.tables and coral.columns
• coral.inputs for source variables and secrets

Default Mode

Default to standalone source authoring for external developers.

That means:

• create a YAML source spec file
• lint it early with coral source lint <path>
• add it to Coral with coral source add --file <path> when you need to exercise it as a source
• validate by querying it
• iterate until the shape is correct

Only switch to Coral repo layout when the user is explicitly editing the Coral repo.

Output Modes

• External authoring:
  • create a standalone source spec such as ./my-source.yaml
  • validate structure with coral source lint ./my-source.yaml
  • load it with coral source add --file ./my-source.yaml when you need to query it through Coral
• Coral repo contribution:
  • write community source specs to sources/community/<name>/manifest.yaml
  • write core source specs to sources/core/<name>/manifest.yaml only when the user is intentionally changing bundled core sources
  • add representative test_queries for a basic smoke/connection check of the source
  • validate with coral source test <name> and repo checks

Workflow

1. Read the provider API docs or inspect the local dataset.
2. Start with one small table and a few columns.
3. Define:
   • source metadata
   • backend
   • base URL or file location
   • auth
   • variables and secrets
   • credential retrieval methods for secrets, including OAuth when the provider supports browser-based setup
   • if authoring a separate kind: identity manifest, identity setup inputs and OAuth method config
   • tables
   • table functions for source-scoped parameterized endpoints
   • filters
   • response extraction
   • pagination
   • typed columns
4. Lint the source spec:
   • coral source lint <path>
5. Validate the source in the right mode:
   • standalone specs: coral source add --file <path> and inspect with coral sql
   • coral source add is non-interactive by default: each input key is read from the matching environment variable. Export required variables and secrets before running, or pass --interactive to be prompted.
   • for OAuth credential methods, run coral source add --interactive --file <path> with no environment value for the target secret so Coral offers the authored credential choices
   • repo sources or already-named sources: coral source test <name>
6. Inspect the exposed shape:
   • inspect coral.tables for visible tables, descriptions, guides, and required filters; keep metadata queries bounded with LIMIT/OFFSET
   • inspect coral.table_functions for source-scoped functions, descriptions, guides, arguments, result columns, kind, and search limits
   • inspect coral.columns for canonical column metadata, including is_virtual and is_required_filter; filter by one table or page large column sets
   • inspect coral.filters for normalized table filter names, types, modes, required flags, and descriptions
   • inspect coral.inputs to verify variables, secrets, defaults, hints, and required flags
7. Query representative tables with coral sql.
8. If you are relying on coral source test, make sure test_queries gives you a basic smoke/connection check for the source.
9. Refine the spec and repeat.