agent-config-lint

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

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

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:

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:

Save to `C:\tools\out.png` <!-- carry-ignore -->

To keep a specific reference out of the check, pass --ignore . 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