| name | atb-cli-tools-skill-generation |
| description | Use this skill when changing agents-toolbelt generation of the `cli-tools` Agent Skill for Claude Code and Codex, including skill targets, default paths, generated SKILL.md content, category ordering, verified tool inventory, or `internal/skill` golden tests. |
ATB CLI Tools Skill Generation
Purpose
Maintain the generated cli-tools skill that exposes verified local binaries to coding agents.
When to use
Use for edits to internal/skill, skill target paths, generated SKILL.md frontmatter/body, category ordering, skill exposure rules, or runtime calls that refresh and persist skills.
Inspect first
internal/skill/skill.go
internal/skill/target.go
internal/skill/testdata/golden_skill.md
internal/skill/*_test.go
cmd/atb/runtime.go functions persistVerifiedSkill and refreshVerifiedTools
internal/catalog/catalog.go for category labels
Repository map
skill.Generate: renders one minimal cli-tools skill from verified, exposable catalog tools.
skill.Write: writes the same content to all requested target paths.
skill.Targets: Claude Code path is .claude/skills/cli-tools/SKILL.md; Codex path is .agents/skills/cli-tools/SKILL.md.
refreshVerifiedTools: verifies both managed and external installed tools before generation.
Standard workflow
- Keep generated skill frontmatter valid Agent Skills YAML with
name: cli-tools and a concrete description.
- Only include tools with
SkillExpose set and successful verification.
- Preserve category ordering from
categoryOrder, with unknown categories sorted after known categories.
- Update
internal/skill/testdata/golden_skill.md whenever generated output intentionally changes.
- Keep target selection behavior consistent with state: stored target IDs are reused;
none means opt out.
Validation commands
- Skill generator tests:
go test ./internal/skill
- Runtime generation tests:
go test ./cmd/atb
- Catalog category impact:
go test ./internal/catalog
- Full gate:
make verify
Common pitfalls
- Do not write generated runtime skills directly during tests except under temp HOME paths.
- Do not list unverified or hidden tools just because they exist in the catalog.
- Default target paths are relative to the user's home directory, not the repository root.
- A generated inventory is intentionally minimal; avoid turning it into tool tutorials.
Escalation
If changing generated skill format, validate the output against the Agent Skills spec and update the golden file in the same change.