| name | dbt-tools-cli-plugin-skill |
| description | Author a new agent skill under plugins/dbt-tools-cli/skills for @dbt-tools/cli; layout, plugin README index, and structural verification. |
| compatibility | Repository dbt-tools-ts; skills under plugins/dbt-tools-cli/skills/. |
dbt-tools-cli plugin skill (authoring)
Triggers
Use this skill when the user asks or implies:
- Add, scaffold, or document a new skill for
@dbt-tools/cli / dbt-tools
- Extend
plugins/dbt-tools-cli/skills/ with another workflow
- Make plugin skills pass repo verification or align with ADR-0007 layout
This is a meta-skill (how to add plugin skills). It does not replace the CLI reference in packages/cli/README.md.
What you are adding
Plugin skills live here:
plugins/dbt-tools-cli/skills/<kebab-case-id>/SKILL.md
They ship with the dbt-tools-cli agent plugin (plugins/dbt-tools-cli/). Per-engine manifests already set skills to ./skills/—you do not edit .codex-plugin, .cursor-plugin, or .claude-plugin just to add another subdirectory skill.
Do not add or edit marketplace entries (.agents/plugins/marketplace.json, .cursor-plugin/marketplace.json) for a new skill inside an existing plugin; marketplaces list plugins, not individual skills.
FQH vs YAML name
- FQH (documentation only):
<plugin-id>:<skill-folder> — for this plugin, dbt-tools-cli: plus the kebab-case directory under skills/ (example: dbt-tools-cli:discover). Plugin id matches plugins/dbt-tools-cli/.claude-plugin/plugin.json name (same across engine manifests). Use FQH in the plugin README Handle column, runbooks, and a single Skill handle (FQH) line under each skill’s main # title.
- YAML
name: Must equal the folder name only (e.g. name: discover). Agent Skills allows lowercase letters, numbers, hyphens only; no : or /. VS Code Agent Skills forbid namespace prefixes in name and may silently skip invalid skills.
- Slash / picker tokens: Hosts apply their own rules (Claude Code plugin namespace, VS Code
/plugin:skill, Codex $, etc.). See Host compatibility in plugins/dbt-tools-cli/README.md.
Authoring steps
-
Pick an id — kebab-case folder name matching the primary CLI command when possible (e.g. discover, explain). Use the same string for YAML name: in SKILL.md. Avoid clashing with existing skills (for example status).
-
Create plugins/dbt-tools-cli/skills/<id>/SKILL.md with frontmatter and body (see skeleton below).
-
Content rules
- Triggers and when to use — help agents discover the skill.
- Commands — link to
packages/cli/README.md for flags and options; prefer dbt-tools schema for discovery and --json where appropriate.
- Workflow order — e.g. artifact check → search → deps; do not paste the full CLI reference.
- Artifact readiness — if the workflow needs
manifest.json / run_results.json, point to the Readiness gate section in status instead of duplicating readiness rules.
- Progressive disclosure — long tables in
references/ under the same skill directory (see exemplar status/references/readiness.md).
-
Link depth — From plugins/dbt-tools-cli/skills/<id>/SKILL.md, the repo root is four levels up (../../../../). Example: ../../../../packages/cli/README.md for flags and extended topics.
-
Index — Add a row to plugins/dbt-tools-cli/README.md skills table: Handle (dbt-tools-cli:<id>), Skill (link to skills/<id>/SKILL.md), (one line). Keep the table’s and sections accurate if you change plugin id or add skills.
./plugins/tests/verify-agent-plugins.sh structural
pnpm lint:report
pnpm coverage:report
pnpm knip
Structural rules and ADR pointer: references/layout-and-verification.md.
Skeleton for a new plugin skill
Use as a starting point (replace my-workflow and fill sections):
---
name: my-workflow
description: One or two sentences for agent discovery; mention dbt-tools and the task.
---
**Skill handle (FQH):** `dbt-tools-cli:my-workflow` (plugin `dbt-tools-cli`, skill directory `my-workflow`). Documentation only; YAML `name` stays `my-workflow`.
Link to [packages/cli/README.md](../../../../packages/cli/README.md) for flags; prefer `dbt-tools schema` and `--json` where appropriate.
- [packages/cli/README.md](../../../../packages/cli/README.md) — Field Filtering, Input
README table row example (match plugins/dbt-tools-cli/README.md):
| `dbt-tools-cli:my-workflow` | [`my-workflow`](skills/my-workflow/SKILL.md) | Short purpose line. |
Related
