lint-skill

Lint a single SKILL.md against the six principles Christian Dussol distilled from Anthropic's official Skills guide. This skill itself was linted with /lint-skill — see references/dussol-principles.md for the full doctrine.

When to invoke

• The user typed /lint-skill <path> or /lint-skill with a recently-discussed skill in context.
• The user asks to "audit", "review", "score", or "check" a skill file.
• The user just generated a new skill with skill-creator or by hand and wants a sanity check before shipping.

When NOT to invoke

• General Markdown linting (use markdownlint).
• Code review of source files inside a skill's scripts/ folder (use /simplify or /security-review).
• Linting MCP server manifests — those follow a different spec, not Dussol's six.

Workflow

Step 1 — Locate the target SKILL.md

Read the path the user provided. If they did not provide one, look for the nearest SKILL.md walking up from the current working directory; if multiple exist, ask which one.

Step 2 — Run the deterministic script

Execute the bundled Python script. It checks the things that do not need an LLM:

Loading code…

The script outputs a per-principle report ([PASS] / [WARN] / [FAIL]) plus exit code 0 on full pass, 1 on any FAIL, 2 on any WARN-but-no-FAIL.

Step 3 — Add the judgment-required principles

Three principles need an LLM eye on top of the script:

• P1 fine-grain check — read the description: and confirm the WHAT, WHEN, and NEGATIVE TRIGGER are each meaningful sentences, not regex bait that the user inserted just to pass the lint. A description like "Use when… Do NOT use for…" with no real content fails.
• P4 example quality — confirm at least one example actually has the three sub-parts (input → expected reasoning → output structure). A bullet list of "examples" with no chain of reasoning does not count.
• P6 trigger harness diversity — if tests/triggers.yml (or equivalent) is present, scan it for at least 10 should-trigger and 10 should-not-trigger entries. If short, surface as WARN.

Step 4 — Print the structured report

Print the script's output verbatim, then your three judgment-based additions. End with one concrete fix suggestion per FAIL/WARN, ranked by impact. Imperative voice: "Add a NEGATIVE TRIGGER sentence to the description", not "It would be good if there were a negative trigger."

Step 5 — Optional auto-fix

If the user says "fix it" or "apply suggestions", apply the smallest safe edits. NEVER rewrite the whole SKILL.md. Touch only the failing field. After editing, re-run the script and confirm green.

Example reasoning chain

Input

Expected reasoning

1. Read the file at ~/projects/myapp/.claude/skills/deploy-helper/SKILL.md.
2. Run python public/skills/mcpflix-skills-linter/scripts/lint-skill.py ~/projects/myapp/.claude/skills/deploy-helper/SKILL.md.
3. Script reports: [PASS] P1 description, [WARN] P2 body is 6,200 tokens, [FAIL] P5 README.md found alongside SKILL.md, [PASS] P6 triggers.yml present with 12 + 11.
4. Manually inspect description: — confirm it has a real WHAT/WHEN/NEGATIVE, not just the marker words.
5. Open the examples section — verify at least one chain is concrete.

Output

Principles checked

The six principles are documented in detail in references/dussol-principles.md with before/after examples in references/examples-good-vs-bad.md. At a glance:

1. Description field — WHAT + WHEN + NEGATIVE TRIGGERS.
2. Progressive disclosure — body ≤ 5K tokens, deep dives in references/.
3. Deterministic scripts — non-LLM checks live in scripts/.
4. Concrete examples — at least one input → reasoning → output chain.
5. No README.md in the skill folder.
6. Triggering harness — 10+ should-trigger and 10+ should-not-trigger prompts under tests/.

Self-lint

This skill was checked with itself. The bundled triggering harness lives in tests/triggers.yml (relative to this folder). To verify:

Loading code…

Expected: all six principles [PASS], exit code 0.