feat(agent-skills): add transitive link traversal to skill validator#56
Merged
feat(agent-skills): add transitive link traversal to skill validator#56
Conversation
validateSkill() now performs BFS link graph traversal after frontmatter validation, checking all local file links for existence and boundary escapes. Linked markdown files are recursively traversed with cycle detection. Supports unreferenced file detection via checkUnreferencedFiles option. Navigation files (README.md, index.md, etc.) and CLAUDE.md are excluded from unreferenced checks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Instead of silently skipping files that exist but fail to parse, emit a LINK_INTEGRITY_BROKEN warning so users know something went wrong. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #56 +/- ##
==========================================
+ Coverage 73.82% 74.22% +0.40%
==========================================
Files 164 164
Lines 12049 12315 +266
Branches 2112 2173 +61
==========================================
+ Hits 8895 9141 +246
- Misses 3154 3174 +20
🚀 New features to boost your workflow:
|
Add system tests verifying: - Dist skills audit scans multiple files without errors - Transitive link following works end-to-end via CLI - Broken links detected via CLI exit code - Unreferenced files reported with --warn-unreferenced-files - CLAUDE.md and README.md never flagged as unreferenced Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Skills are LLM-interpreted, so file references in code blocks and prose are functionally valid even without formal markdown inline links. Documents this pattern observed in official Claude Marketplace plugins (superpowers) and recommends using inline links for auditability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Encourage AI assistants to run vat audit --user as best-effort QA when changing audit, validation, or link traversal code. Not a hard gate — agentic guidance to catch regressions in real-world usability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…positive unreferenced file warnings Adds extractImplicitReferences() that scans BFS-visited files for non-markdown-link references to companion files (backtick-quoted, bold, DOT graphviz, bare prose, @-prefix). Files found via implicit reference now get SKILL_IMPLICIT_REFERENCE instead of SKILL_UNREFERENCED_FILE, eliminating false positives for real-world skill conventions. Reduces unreferenced file false positives from 18 to 9 when auditing installed plugins. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
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
vat auditfor standalone skills (SKILL.md files not in a VAT project)LINK_INTEGRITY_BROKENerror), boundary escapes (OUTSIDE_PROJECT_BOUNDARYwarning), and unreferenced markdown files (SKILL_UNREFERENCED_FILEinfo with--warn-unreferenced-files)Test plan
🤖 Generated with Claude Code