# agent-skill-linter (William-Yeh/agent-skill-linter)

Notes captured from the GitHub repository page and README at fetch time.

## What it is

> Lint agent skills for spec compliance and publishing readiness.

A linter that checks an agent-skill repository against the SKILL.md spec plus a set of publishing-readiness conventions (license, README badges, CI workflow, code structure). Designed for the cross-harness "Agent Skills" ecosystem (Claude Code, Cursor, Gemini CLI, Amp, Roo Code, Copilot) registered at agentskills.io.

Implementation: 100% Python. Dependency manager: `uv`. CLI entry point: `scripts/skill-lint.py`.

## Repo metadata (GitHub API)

- `William-Yeh/agent-skill-linter`
- Created 2026-02-12; last push 2026-04-24
- 2 stars, 1 fork, 0 open issues
- Latest release: v0.11.0 (April 2026), 4 releases total
- Apache-2.0 license
- Primary language: Python
- Repo size: 63 KB

## Lint rules (~21 active)

Categorised by what they check:

**Specification & metadata**
- SKILL.md spec compliance (via `skills-ref`) — Error
- Frontmatter `author` field validation — Warning, fixable

**Licensing**
- LICENSE exists, Apache-2.0 or MIT, current year — Warning, partially fixable

**Documentation**
- README badges for CI, license, Agent Skills compatibility — Warning, fixable
- Installation section required — Warning, fixable
- Usage section with prompt examples — Warning
- CLI usage subsection guidance — Info

**Infrastructure**
- `.github/workflows/` has CI workflow — Warning, fixable

**Code quality & structure**
- Python script consistency (uv invocation patterns)
- Template and reference file organization
- Repository structure isolation
- Content scope division (README vs. SKILL.md)

**Advanced**
- File line limits (SKILL.md under 500 lines) — Info
- PEP 723 inline dependency metadata for entry scripts — Warning
- Workflow triage semantic review steps — Info

## Install

Skill (cross-harness):

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

Manual install — copy the `skill/` directory:

- Claude Code: `~/.claude/skills/agent-skill-linter/`
- Cursor: `.cursor/skills/agent-skill-linter/`

## CLI usage

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

## Agent prompts

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

## Author and ecosystem

- Author: William-Yeh
- Targets the `agentskills.io` registry
- Spec source-of-truth referenced as `skills-ref`
- Severity model: Error / Warning / Info, with `--fix` for the fixable subset