feat(plugins): add four dbt-tools CLI agent skills#154
Conversation
Add status, discover-search, deps, and explain-impact skills under plugins/dbt-tools-cli/skills/ so AI coding agents can investigate dbt artifacts through documented, self-contained workflows. Each skill includes a SKILL.md (YAML frontmatter, trigger scenarios, command patterns, failure handling) and a references/commands.md cheat sheet. The plugin README index is updated to list all five skills. https://claude.ai/code/session_01UHugRewaSvf3ty4ASLvPES
Auto-format YAML frontmatter, table column alignment, and JSON examples in the four new dbt-tools-cli agent skill files to match Trunk/Prettier conventions. https://claude.ai/code/session_01UHugRewaSvf3ty4ASLvPES
The compound name was redundant — discover subsumes search semantically. Single-word names mirror the primary CLI command (dbt-tools discover) and require no disambiguation suffix. Updates: directory rename, frontmatter name:, all cross-references in deps/SKILL.md, explain-impact/SKILL.md, and the plugin README index. https://claude.ai/code/session_01UHugRewaSvf3ty4ASLvPES
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 55f0121f92
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| dbt-tools discover --dbt-target ./target --type model --json | ||
|
|
||
| # Discovery with paging | ||
| dbt-tools discover --dbt-target ./target "orders" --json --limit 10 --offset 0 |
There was a problem hiding this comment.
This command example will fail because discover does not accept --offset; the CLI only defines --limit for discover (see packages/dbt-tools/cli/src/cli.ts, discover options) while paging with --offset is implemented for search/inventory. As written, agents following this recipe get an unknown-option error instead of usable discovery output.
Useful? React with 👍 / 👎.
| | Reasons for each match | Yes (`reasons` array) | No | | ||
| | Disambiguation peers | Yes (`disambiguation`) | No | | ||
| | Suggested next steps | Yes (`next_actions`, `primitive_commands`) | No | | ||
| | Requires `run_results.json` | No (manifest-only) | Manifest + run_results | |
There was a problem hiding this comment.
The table says search requires manifest + run_results, but the implementation resolves artifacts with { manifest: true, runResults: false } in searchAction (packages/dbt-tools/cli/src/actions/explore/search-action.ts), so search is usable in manifest-only states. This incorrect requirement can cause agents to skip valid search flows when run_results.json is absent.
Useful? React with 👍 / 👎.
| "unique_id": "model.my_project.orders", | ||
| "affected": [ |
There was a problem hiding this comment.
The documented impact payload shape is incompatible with the current CLI output contract: impactAction returns target.resolved_unique_id and an impact object (upstream_count, downstream_count, critical_dependents) rather than top-level unique_id plus affected. Agents or scripts built from this reference will parse nonexistent fields and fail to extract impact results.
Useful? React with 👍 / 👎.
P1 — Remove --offset from discover recipe: dbt-tools discover does not
support --offset (only --limit). Fix the recipe and clarify in the note.
P2 — Correct search readiness: search resolves artifacts with
manifest-only (runResults: false), same as discover. Fix the comparison
table and the decision guidance row.
P2 — Fix impact JSON example: the CLI returns {intent, contract_version,
target.resolved_unique_id, impact.{upstream_count, downstream_count,
critical_dependents}} not a top-level affected array. Update the example
to match the actual contract and add parse guidance.
https://claude.ai/code/session_01UHugRewaSvf3ty4ASLvPES
2 participants
Add status, discover-search, deps, and explain-impact skills under
plugins/dbt-tools-cli/skills/ so AI coding agents can investigate dbt
artifacts through documented, self-contained workflows.
Each skill includes a SKILL.md (YAML frontmatter, trigger scenarios,
command patterns, failure handling) and a references/commands.md cheat
sheet. The plugin README index is updated to list all five skills.
https://claude.ai/code/session_01UHugRewaSvf3ty4ASLvPES