listing-objects

name	listing-objects
description	Use when the user asks to "list tables", "list procedures", "show me object X", "what references Y", or wants to browse catalog contents.
user-invocable	true
argument-hint	<subcommand> [object]

Listing Objects

Read-only catalog viewer. Displays whatever state exists in the catalog.

Arguments

$ARGUMENTS is a subcommand followed by a type or object name. If no subcommand is given, default to list.

Subcommand	Argument	Description
list	tables, sources, seeds, procedures, views, or functions	Enumerate objects by type
show	<schema.object>	Display catalog state for one object
refs	<schema.object>	Show procedures/views that reference an object

Before invoking

No stage guard. This skill is read-only — it shows whatever exists in the catalog. The CLI commands handle missing catalog files via their own exit codes.

Use the canonical surfaced code list in ../../lib/shared/listing_objects_error_codes.md.

Output shapes

All CLI commands return JSON. Key fields: objects[] (list), columns/refs/statements (show), readers/writers (refs). Fields are null or [] when not applicable to the object type.

list

uv run --project "${CLAUDE_PLUGIN_ROOT}/packages/ad-migration-internal" discover list \
  --type <type>

Present as a numbered list. If the user selects an object, proceed to show. If they ask what references it, proceed to refs.

list sources returns only confirmed source tables persisted as is_source: true in the catalog. list seeds returns only confirmed seed tables persisted as is_seed: true in the catalog. Neither result should be described as an active migration table list.

If objects[] is empty, say there are no objects of that type in the current catalog state. Do not troubleshoot fixtures or infer missing extraction steps unless the user asks.

show

uv run --project "${CLAUDE_PLUGIN_ROOT}/packages/ad-migration-internal" discover show \
  --name <fqn>

Present whatever the catalog currently holds for the object.

Do not special-case is_source tables. If discover show returns columns for a source table, present them as normal catalog state. For a direct show <schema.object> request, run discover show once and treat a successful payload as the source of truth for the response. Present the returned catalog state directly. Do not inspect sibling files, diagnose catalog/setup problems, or infer missing extraction steps unless discover show itself fails.

If discover show includes is_source: true, surface that the table is a confirmed source. If discover show includes is_seed: true, surface that the table is a confirmed dbt seed.

Tables: columns, plus scoping results and analyzed statements if present.

Views: refs and definition.

Procedures: parameters, refs, statements if analyzed, raw DDL summary.

refs

uv run --project "${CLAUDE_PLUGIN_ROOT}/packages/ad-migration-internal" discover refs \
  --name <fqn>

Present writers (procs that modify the object) and readers (procs/views that select from it), grouped.

If the payload contains error, surface that error instead of inventing refs output from other catalog data.

Error handling

Use the canonical listing-objects code list in ../../lib/shared/listing_objects_error_codes.md.

Map command results like this:

Command	Exit code / payload	Action
discover list/show	1	Surface OBJECT_NOT_FOUND, then stop
discover list/show/refs	2	Surface CATALOG_IO_ERROR, then stop
discover refs	payload error saying the target is a procedure or unsupported target for refs	Surface UNSUPPORTED_OBJECT_TYPE, include the returned guidance, do not ask a follow-up question, do not fall back to show, then stop
discover refs	payload error saying no catalog file for ...	Surface OBJECT_NOT_FOUND, then stop
discover show	parse_error / parse warning in payload	Surface PARSE_ERROR or DDL_PARSE_ERROR as a warning and continue showing available raw catalog state