docs(skill): ship SKILL.md and declare violation codes frozen#20
Merged
Conversation
Wave 4 of the roadmap — closes the "AI tools placing files incorrectly" use case with a real agent surface instead of a docs jungle. Spec: docs/specs/011-agent-skill.md. - skills/structlint/SKILL.md — agent-facing skill shipped in-repo at the root (not under .claude/, since it's a distributed artifact for consumers). Frontmatter with trigger phrases, when-to-run guidance, full decision table for the 13 violation codes (fix tree vs fix config), machine contracts (validate --format json shape, suggest JSON v1), the fix loop (suggest → patch/git mv → validate), setup recipes (hook install / pre-commit / GitHub Action / extends / schema modeline), and gotchas. - docs/user/violation-codes.md — canonical reference declaring the 13 codes frozen and append-only. Codes are a public contract; agents and CI parsers key on them, so they never rename or disappear. - .structlint.yaml gains skills/** in allowedPaths (self-validation lockstep — roadmap risk 5). - README.md gains a "Documentation" row for the codes doc and a dedicated "For AI agents" section pointing to SKILL.md. - docs/AI/overview.md gains a preamble routing agents to SKILL.md. Tests (test/skill_contract_test.go): - Every code in the CodeDescriptions registry has an entry in the codes doc AND in the SKILL.md decision table (both directions enforced — new codes without docs and stale docs both break CI). - SKILL.md starts with a frontmatter block declaring name + description. - Self-validation passes with the new skills/ directory (proves the .structlint.yaml update landed alongside).
StructLint — All checks passed134 rules validated against
|
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
Layout decision
`skills/` at the repo root, not `.claude/`. The skill is a distributed artifact for consumers (they install it into their own agent setups, or read it from the release/repo). `.claude/` is local tooling config for structlint's own development.
Cross-links
Test plan
Roadmap complete
This closes the 11-spec roadmap. Full arc: `--staged` mode → `hook install` → pre-commit packaging → summary-by-code → rule engine → config discovery → `extends` presets → JSON schema → `init --infer` → `suggest` → agent skill.