Capture judgment: cobra mining, anti-patterns, skills lint#3
Merged
Conversation
The v0.2 library optimized for coverage (every command documented).
The bottleneck for agent usefulness is judgment — when to trigger and
what to avoid. This commit captures that judgment cheaply, in three
coordinated changes.
Cobra field mining
------------------
Before consulting annotations, the generator now reads free signal
from the command tree:
- cmd.Aliases render as "Aliases: `ship`, `release`" and auto-derive a
trigger suffix when skill.trigger is unset ("Use when the user asks
to deploy, ship, or release").
- cmd.Deprecated renders a prominent "> **Deprecated:** …" callout so
agents are warned off the command and see the replacement.
- Deprecated flags (pflag.Flag.Deprecated) are filtered from the
rendered flag list entirely — the author already said the flag
shouldn't be suggested.
deriveDescription consolidates the three previously duplicated
description-composition blocks (single / leaf / overview) so the alias
fallback applies consistently.
Anti-pattern annotations
------------------------
Two new annotations, the single highest-value content in most real
skills:
- skill.avoid — free-form Markdown rendered as a ## Avoid section in
root / leaf bodies and as a bold inline label inside nested command
sections.
- skill.prefer-over — same treatment under ## Prefer over, for
pointing the agent away from competing tools or commands this one
supersedes.
skills lint
-----------
Generator.Lint() walks the same tree the generator walks (honoring
Hidden, skill.skip, WithSkip, and the cobra-builtin filter) and
returns []Issue — errors for missing descriptions, warnings for short
Short, missing trigger signal on root/leaves, and deprecated commands
without a useful message. `skills lint` prints the findings; exit
code is 1 on any error, and --strict promotes warnings to errors for
CI enforcement.
Tests
-----
14 new tests in judgment_test.go covering alias rendering + trigger
derivation, explicit trigger precedence, deprecated callouts, flag
filtering, anti-pattern sections (root-level and nested), lint's
positive and negative paths, skip honoring, sort order, and the empty
case of FormatIssues.
Docs
----
README gains an annotations row for skill.avoid / skill.prefer-over,
a new "What's mined from cobra" section, and a "Linting" section with
a GitHub Actions snippet. CHANGELOG picks up the three Added entries
under Unreleased.
This was referenced Apr 18, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cobra field mining
Before consulting annotations, the generator now extracts free signal:
cmd.Aliases→ render as anAliases: …note and auto-derive trigger phrases whenskill.triggeris unset ("Use when the user asks to deploy, ship, or release").cmd.Deprecated→ renders a prominent> **Deprecated:** …callout.flag.Deprecated→ filtered from the rendered flag list entirely.Also refactored:
deriveDescriptioncollapses three previously duplicated description-composition blocks (single / leaf / overview) so the alias fallback applies consistently.Anti-pattern annotations
skill.avoid— free-form Markdown rendered as a## Avoidsection (bold inline label inside nested command sections).skill.prefer-over— same treatment under## Prefer over.These capture the single highest-value content in most real skills: what not to do.
skills lintGenerator.Lint()walks the same tree the generator walks (honors Hidden /skill.skip/WithSkip/ cobra builtins) and returns[]Issue.Short, missing trigger signal on root/leaves, and deprecated commands without a useful message.skills lintsubcommand prints findings + summary, exits 1 on any error.--strictpromotes warnings to errors for CI.Test plan
go build ./...go test ./...— 14 new tests injudgment_test.gopass alongside the existing suitego vet ./...golangci-lint run ./...— 0 issuesgo run ./example skills lint— 3 trigger warnings, exit 0go run ./example skills lint --strict— same output, exit 1go run ./example skills print— aliases/deprecated/anti-pattern sections render as expected when wired into cobra commands