Map

agent-skill-linter

Toolbox toolboxpythonskillslintingai-agentswatchlistPythonApache-2.0 ↳ show in map Markdown
title
agent-skill-linter
type
toolbox
summary
Lints agent skill bundles for spec compliance and publishing readiness, with auto-fix
tags
python, skills, linting, ai-agents, watchlist
repo
https://github.com/William-Yeh/agent-skill-linter
language
Python
license
Apache-2.0
created
2026-05-02
updated
2026-05-02

Linter for agent-skill repositories: checks SKILL.md against the spec, then runs a publishing-readiness pass over LICENSE, README badges, CI workflow, code structure, and Python script style. Targets the cross-harness Agent Skills ecosystem — the same skill bundle works in Claude Code, Cursor, Gemini CLI, Amp, Roo Code, and Copilot — registered at agentskills.io.

Position: this is the linter that gates whether a skill is "ready to publish on the registry," not a runtime correctness checker. Closest analogue in shape is markdownlint or actionlint — domain-specific lint with auto-fix for the easy stuff.

What it checks (~21 rules)

Severity tiers are Error / Warning / Info; a subset of warnings have --fix available.

Spec & metadata

  • SKILL.md spec compliance (via the skills-ref reference) — Error
  • Frontmatter author field present and valid — Warning, fixable

Licensing

  • LICENSE exists, is Apache-2.0 or MIT, has current year — Warning, partially fixable

Documentation

  • README has badges for CI, license, Agent Skills compatibility — Warning, fixable
  • Installation section present — Warning, fixable
  • Usage section with prompt examples — Warning
  • CLI usage subsection — Info

Infrastructure

  • .github/workflows/ has at least one CI workflow — Warning, fixable

Code quality

  • Python script invocation patterns are consistent (uv-style)
  • Template and reference files are organised under expected paths
  • Repo structure keeps the skill isolated
  • Content scope is divided cleanly between README and SKILL.md

Advanced

  • SKILL.md is under 500 lines — Info (context-window discipline)
  • Entry scripts use PEP 723 inline dependency metadata — Warning
  • CI workflows include a semantic-review triage step — Info

Install

The cross-harness one-liner uses the skills installer that's becoming the de facto convention for skill bundles (also used by impeccable):

npx skills add William-Yeh/agent-skill-linter

That drops the skill into every supported harness's directory at once. Manual install is also documented:

# Claude Code
cp -r skill/ ~/.claude/skills/agent-skill-linter/

# Cursor
cp -r skill/ .cursor/skills/agent-skill-linter/

Once installed, the skill teaches the agent how to invoke the linter via natural-language prompts:

"Lint the skill in this directory for publishing readiness." "Check ~/projects/my-skill for spec compliance and fix any issues."

CLI usage

The Python entry point can also be run directly without the agent harness:

./scripts/skill-lint.py check ./my-skill
./scripts/skill-lint.py check . --fix
./scripts/skill-lint.py check ./my-skill --format json

JSON output exists specifically so the agent can feed lint results back into its own loop and act on them.

Why a deterministic linter for skills

Same argument as the impeccable detector half: an LLM scoring an LLM's output runs into shared training-data bias, so the cheap-and-explainable rule beats the smart-and-fuzzy judge for "did you forget the LICENSE file." The 21-rule count is small on purpose — this is a publish-readiness checklist, not a quality bar. Anything subjective belongs upstream of the linter.

Status

Three months old (created 2026-02-12), 2 stars, 1 fork, single author (William-Yeh), 4 releases up to v0.11.0 (April 2026), 0 open issues. The aggressive 0.x release cadence is a good sign for active maintenance; star count is the discouraging counter-signal — the cross-harness skill ecosystem is small enough that a useful tool here probably only gets noticed when the registry it gates (agentskills.io) catches on.

Filed on watchlist — re-check 2026-08-02. Watching for: registry adoption, second contributor, expansion past the William-Yeh-authored set of skills.

Limitations

  • Python skills only on the deeper checks (PEP 723, uv invocation). Skill bundles in TypeScript/JS get the doc/license/CI rules but not the language-specific ones.
  • Dependent on the skills-ref spec staying authoritative — if the registry changes hands or fragments, the linter chases.
  • No editor integration yet (no LSP, no pre-commit hook in the repo); CLI / agent prompt are the only entry points.
  • Two stars is an ecosystem-size signal, not a quality signal — the tool is plausibly fine and just lives in a niche.
  • mcp-vs-skills — context for what an "agent skill" even is and why portable skills matter.
  • impeccable — same npx skills add ... install pattern, same deterministic-lint philosophy, different domain (visual design clichés).
  • claude-defuddle — example of a single-purpose Claude Code skill that this linter would target.
  • clippy-stricter-config — the equivalent "publish-readiness lint config" instinct in Rust.

Repo

github.com/William-Yeh/agent-skill-linter · 2★ · Apache-2.0 · Python · v0.11.0

Source: agent-skill-linter-readme.

Linked from