# agent-skill-linter

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](https://peps.python.org/pep-0723/) inline dependency metadata — Warning
- CI workflows include a semantic-review triage step — Info

## Install

The cross-harness one-liner uses the [`skills`](https://www.npmjs.com/package/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:

```bash
./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 [[toolbox/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.

## Related

- [[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](https://github.com/William-Yeh/agent-skill-linter) · 2★ · Apache-2.0 · Python · v0.11.0

Source: [[agent-skill-linter-readme]].