Audits every code snippet in the XL1 skills against this repo's import-hygiene rules. Report-only by default — only edits files when invoked with --fix, and only for the mechanical checks.
Scope
plugins/xl1-skills/skills/**/*.md— all skill markdownplugins/xl1-skills/skills/xl1-scaffold/scripts/scaffold/templates/**— scaffold templates
Ignore everything else. Do not edit application code under src/.
Project rules being checked
- Prefer root-barrel imports for tree shaking. The four root barrels:
@xyo-network/sdk-js@xyo-network/xl1-sdk@xyo-network/chain-sdk@xyo-network/react-chain-client-sdk
- Fall back to a sub-package only when a symbol is genuinely not re-exported through a barrel (e.g. storage drivers like
StorageArchivistcome from@xyo-network/archivist-storage). - The same symbol should be imported from the same package across all skills.
- Every package referenced in a skill must be installable via the scaffold templates.
Invocation
/audit-imports [check] [--fix]
| Argument | Effect |
|---|---|
| (none) | Run all six checks |
barrels |
Symbols missing from the named root barrel |
inverse |
Sub-package imports that the root barrel already covers |
consistency |
Same symbol sourced from different packages across skills |
subpaths |
Subpath imports (pkg/test) not declared in exports |
usage |
Unused or apparently-missing imports inside a snippet |
scaffold |
Skill-referenced packages that aren't in any scaffold template |
--fix |
Apply mechanical edits for barrels, inverse, and consistency only |
Execution plan
The slow part is fetching package metadata over the network. Cache it once, then run analysis in parallel.
Phase 1 — Inventory (sequential, local)
Use Grep to collect every import ... from '@xyo-network/...' line under the scope above. Build:
imports[]—{ file, line, package, subpath?, symbols: string[], typeOnly: bool }packages— the unique set of@xyo-network/*packages referenced
For markdown skills, only consider imports that appear inside fenced code blocks (ts / tsx). Ignore imports in prose or comments.
Phase 2 — Cache barrel exports (parallel agents)
For each unique package in packages, spawn an Explore agent in parallel (one Agent tool call per package, all in a single message). Each agent:
- Fetches
https://registry.npmjs.org/<encoded-pkg>/latestto get the latest version andexportsfield. - Fetches the published
index.d.tsviahttps://unpkg.com/<pkg>@<version>/<entry>(entry comes from theexportsortypesfield). Falls back tosrc/index.tsfromhttps://raw.githubusercontent.com/XYOracleNetwork/<repo>/main/...if unpkg 404s. - Parses the
.d.tsfor top-levelexportdeclarations — both value and type — includingexport *re-exports (recurse one level if needed). - Writes
/tmp/xyo-barrel-exports.<package-slug>.jsonwith shape:{ "package": "@xyo-network/foo", "version": "x.y.z", "exports": { "field": [...], "symbols": ["A", "B"] }, "fetched_at": "ISO-8601" } - If anything fails (404, parse error, private package), writes the same file with
"error": "<reason>"so the parent doesn't refetch.
Cache files are reused across runs — skip the fetch if /tmp/xyo-barrel-exports.<slug>.json exists and is less than 24 h old. Pass an explicit "ignore cache" flag to bust it (/audit-imports --refresh).
Phase 3 — Run checks (parallel agents)
Spawn one general-purpose agent per requested check, all in a single message. Each agent reads the cache files from Phase 2 and produces its report section. Checks:
barrels— for each import where the package is one of the four root barrels, verify every named symbol is in that barrel'ssymbolsset. Missing symbols → find which sub-package's cache contains the symbol, recommend that.inverse— for each import where the package is a sub-package, check whether every symbol is also re-exported from one of the four root barrels. If yes, recommend switching.consistency— buildsymbol → set(packages)across all callsites. Any symbol with|set| > 1is a finding. Recommend the preferred source: root barrel if it exports the symbol; otherwise the most-used sub-package.subpaths— for any import with a subpath, verify the subpath is in the package'sexportsfield (from the cachedpackage.json). Report undeclared subpaths.usage— within each fenced code block, parse named imports and check each appears at least once in the rest of the block. Also flag PascalCase identifiers used in the block that look like SDK symbols but aren't imported. Be conservative — only flag obvious cases.scaffold— read everytemplates/*/package.jsonunder the scaffold templates dir. Confirm each@xyo-network/*package referenced in a skill appears as adependencyorpeerDependencyin at least one template. Report orphans.
Output format
## Check N: <name>
### Findings (<count>)
- <one-line summary>
- plugins/xl1-skills/skills/<file>.md:<line> — `<current>` → `<recommended>`
### Unverified
- <package> — <reason>
End with a summary table:
| Check | Files scanned | Findings | Unverified |
|---|---|---|---|
| barrels | … | … | … |
| … |
--fix behavior
If --fix is passed, after producing the report apply mechanical edits for checks 1, 2, and 3 only:
- Use
Editto rewrite thefrom '@xyo-network/...'portion of the offending import line. - Never merge two import lines together. Never reorder symbols. Never touch surrounding text.
- Re-run Phase 1's grep after editing and confirm the diff matches the report.
Do not auto-fix subpaths, usage, or scaffold — these are judgment calls (a missing subpath might be a typo or a real bug; an unused import might be intentional in a partial example; a scaffold orphan might mean the skill is wrong or the scaffold needs the dep).
Notes
- Skip imports with
// audit-imports: ignoreon the same line. - For type-only imports (
import type { X } from ...), check the same way — type re-exports must also be present in the barrel. - If two checks would produce the same edit (e.g.
barrelsandconsistencyboth want to move a symbol),barrelswins — it's the more specific finding.