MCPFlixFree Beta
Official⭐ Featuredworkflow

MCPFlix Skills Linter

Audit any Claude Code SKILL.md against Christian Dussol's six skill-authoring principles (description quality, progressive disclosure, deterministic scripts, concrete examples, no README collision, triggering harness). Use when the user has authored, imported, or is reviewing a SKILL.md file and asks for a quality check, lint, audit, review, or score. Use when the user types `/lint-skill` followed by a path. Do NOT use for general code review of non-skill files, do NOT use for Markdown linting at large, and do NOT use for linting MCP server manifests (those follow a different spec).

/lint-skillSource

Install this skill

  1. 1. Copy the SKILL.md content (button above)
  2. 2. Create a folder for the skill:
    # Mac/Linux
mkdir -p ~/.claude/skills/mcpflix-skills-linter

# Windows (PowerShell)
mkdir $env:USERPROFILE\.claude\skills\mcpflix-skills-linter
  3. 3. Save the content as ~/.claude/skills/mcpflix-skills-linter/SKILL.md
  4. 4. Restart Claude Code (or open a new session)
  5. 5. Type /lint-skill to invoke it
skillslintauditdussolbest-practices

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

/lint-skill ~/projects/myapp/.claude/skills/deploy-helper/SKILL.md

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

deploy-helper • lint report [PASS] P1 Description (Dussol) — WHAT/WHEN/NEGATIVE all present and substantive. [WARN] P2 Progressive disclosure — body is 6,200 tokens (>5K). Extract the "Cloud provider matrix" section to references/cloud-providers.md. [FAIL] P5 No README collision — README.md found at ~/projects/myapp/.claude/skills/deploy-helper/README.md. Rename to references/overview.md or delete. [PASS] P3 Deterministic scripts — scripts/validate-env.sh referenced. [PASS] P4 Concrete example — "blue-green rollout" chain has input/reasoning/output. [PASS] P6 Trigger harness — tests/triggers.yml has 12 positive + 11 negative. Suggested fixes (most impactful first): 1. Delete or rename README.md (blocks Claude from loading the right instructions). 2. Extract the "Cloud provider matrix" section to references/cloud-providers.md.

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.

← Back to all skillsBuild a custom skill