Agent config lint
Agent config fails quietly. A SKILL.md points at a script that was renamed, an
AGENTS.md hardcodes the author's home directory, two skills describe themselves so
similarly the agent picks the wrong one. Nothing throws — the agent just does the wrong
thing, and only on someone else's machine.
This skill runs tenken, which bundles three zero-dependency linters in one pass.
When to use
Run it when any of these is true:
- about to commit or publish a
SKILL.md,AGENTS.md,CLAUDE.mdorllms.txt - about to publish a skill to ClawHub
- a skill works for the author but not for a teammate
- a skill is not firing, or the wrong skill fires
- the user asks to review or check agent config
How to run
npx @hyuga/tenken
Scan a specific path:
npx @hyuga/tenken path/to/skills
Machine-readable output, for when you need to act on individual findings:
npx @hyuga/tenken --format json
Exit code is 0 when clean, 1 when there is at least one error, 2 on bad usage.
Warnings do not fail unless --strict is passed.
What it catches
| a back-quoted path or markdown link that does not resolve | reference rot |
/Users/<name>/…, C:\Users\<name>\… |
will not resolve for anyone else |
| an external CLI the document never declares or installs | missing dependency |
an unresolved <FILL_ME> / REPLACE_ME left in a shipped file |
unfinished |
frontmatter name that does not match the skill's directory |
installs under a different identity |
missing name or description |
the agent has no trigger to match on |
| two descriptions ≥0.7 similar | the agent fires the wrong skill |
Reading the output
Each line is [engine] file:line message. Lines marked ! are warnings.
✗ .claude/skills/report/SKILL.md — 2 problems
[skills-lint] .claude/skills/report/SKILL.md:1 name "Report_Skill" does not match its directory "report"
[skills-lint] .claude/skills/report/SKILL.md:12 reference `scripts/build-report.py` does not exist
Fix in this order, because the first two stop the skill from working at all:
- missing or malformed frontmatter — the agent cannot trigger the skill
namenot matching the directory — it installs under an identity nobody can find- absolute paths and undeclared CLIs — it breaks on the next machine
- broken references — the agent reads something that is not there
Suppressing a finding
When a path or dependency is deliberate:
Save to `C:\tools\out.png` <!-- carry-ignore -->
To keep a specific reference out of the check, pass --ignore <path>. To allow a CLI the
document intentionally depends on, pass --allow codex,gemini.
Scope
Static analysis only. It runs no model and needs no API key, so it costs nothing to run on every commit and returns the same answer every time. It does not check whether a skill is good — only whether it will still work once it leaves the machine it was written on.
For prompt-injection, malware and supply-chain scanning, use a security scanner instead; this is a hygiene and portability check and does not replace one.
Source and issues: https://github.com/hyuga611/tenken