agent-config-lint

Check agent config for things that break silently on someone else's machine. Use before publishing or committing a SKILL.md, AGENTS.md, CLAUDE.md or llms.txt, before publishing a skill to ClawHub, when a skill "works on my machine" but not for a teammate, when a skill fails to trigger, or when asked to review agent config. Catches references to files that do not exist, absolute paths under the author's home directory, undeclared CLI dependencies, a frontmatter name that does not match the skill's directory, and two skills whose descriptions are so similar the agent fires the wrong one.

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.md or llms.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

bash

npx @hyuga/tenken

Scan a specific path:

bash

npx @hyuga/tenken path/to/skills

Machine-readable output, for when you need to act on individual findings:

bash

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.

text

✗ .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:

1. missing or malformed frontmatter — the agent cannot trigger the skill
2. name not matching the directory — it installs under an identity nobody can find
3. absolute paths and undeclared CLIs — it breaks on the next machine
4. broken references — the agent reads something that is not there

Suppressing a finding

When a path or dependency is deliberate:

md

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