agent-skills-lint

Cross-agent skill validator, installer, and index generator. One tool for Claude Code, Codex, OpenCode, Aider, Copilot, Cursor, Gemini, Droid, Trae, Kiro — and more.

Why this exists

Every coding agent now ships a "skills" feature — and every one uses a slightly different file layout, a slightly different frontmatter schema, and a slightly different install path. You install skills from three different repos and end up with:

• one skill silently overriding another because their names collide
• a typo in a frontmatter field that nobody catches until an agent just quietly ignores the skill
• fifteen .md files in ~/.claude/skills/ with no index, no versioning, and no idea which came from where

agent-skills-lint is the first tooling layer on top of the skills content ecosystem. It validates skill files against per-agent schemas, installs them safely (collision-aware) into the right directory for your agent of choice, and generates an index so you always know what's installed.

Most agents use the same name + description frontmatter pattern — we validate that core schema across all of them, and layer on per-flavor rules (Cursor's .mdc files with globs/alwaysApply, OpenClaw's richer version + metadata fields, etc).

30-second demo

# Validate every skill in your Claude Code install
npx @swarmclawai/agent-skills-lint@latest lint ~/.claude/skills

# Install a skill for OpenAI Codex (uses ~/.agents/skills/<name>/SKILL.md)
npx @swarmclawai/agent-skills-lint --flavor codex install ./my-skill.md

# Generate a CLAUDE.md-style index of everything you've installed
npx @swarmclawai/agent-skills-lint index --dir ~/.claude/skills --write

# Catch name collisions across multiple installs
npx @swarmclawai/agent-skills-lint collisions --dir ~/.claude/skills

Install

pnpm add -g @swarmclawai/agent-skills-lint
# or
npm i -g @swarmclawai/agent-skills-lint
# or run on demand
npx @swarmclawai/agent-skills-lint@latest --help

Supported agents

Each --flavor knows the right file extension, frontmatter schema, and user install root.

Flavor	Agent	User install root	File format
claude (default)	Claude Code	~/.claude/skills/	name.md
codex	OpenAI Codex CLI	~/.agents/skills/<name>/SKILL.md	bundle
opencode	OpenCode	~/.config/opencode/skills/<name>/SKILL.md	bundle
aider	Aider	~/.aider/<name>/SKILL.md	bundle
copilot	GitHub Copilot / VS Code	~/.copilot/skills/<name>/SKILL.md	bundle
gemini	Google Gemini CLI	~/.gemini/skills/<name>/SKILL.md	bundle
cursor	Cursor	.cursor/rules/<name>.mdc	.mdc
claw	OpenClaw	~/.openclaw/skills/<name>/SKILL.md	bundle
droid	Factory Droid	~/.factory/skills/<name>/SKILL.md	bundle
trae	Trae	~/.trae/skills/<name>/SKILL.md	bundle
trae-cn	Trae CN	~/.trae-cn/skills/<name>/SKILL.md	bundle
hermes	Hermes	~/.hermes/skills/<name>/SKILL.md	bundle
kiro	Kiro	~/.kiro/skills/<name>/SKILL.md	bundle
antigravity	Antigravity	~/.agent/skills/<name>/SKILL.md	bundle
generic	Any agent with frontmatter markdown	~/.agent-skills/	.md

Run agent-skills-lint flavors --json for the machine-readable list.

Commands

Command	Purpose
lint <path>	Validate a skill file or directory against the chosen flavor's schema
install <source>	Copy a skill from a file, directory, or HTTPS URL into the agent's skills dir
index	Generate a markdown index (CLAUDE.md-compatible) from a skills dir
collisions	Find skills with duplicate names
flavors	List supported agents and their install paths
help-agents	Print the full machine-readable command catalog as JSON

Every command accepts --json and returns a one-line JSON envelope:

{"ok": true, "data": {...}}

or on error:

{"ok": false, "error": {"code": "E_VALIDATION", "message": "..."}}

See AGENTS.md for the full agent-facing reference and the exact JSON contract per command.

Built for coding agents

This is a CLI made for Claude Code, Cursor, Cline, Codex, Aider and their kin to drive:

• Non-interactive by default. No prompts. Missing inputs error cleanly with a stable code.
• --json everywhere. Every data-returning command produces a single-line JSON envelope.
• Stable exit codes. 0 = success, 1 = user error (validation / lint failure), 2 = internal error.
• Stdout for data, stderr for logs. Pipe-safe by default.
• help-agents — one JSON call returns the full command catalog so an agent can discover every flag without scraping --help.

How it compares

	agent-skills-lint	obra/superpowers	karpathy-skills	awesome-claude-code
Validates frontmatter	✅	❌	❌	❌
Detects name collisions	✅	❌	❌	❌
Safe install with collision check	✅	copy-paste	copy-paste	discovery only
Cross-agent (15 flavors)	✅	Claude only	Claude only	Claude only
Index generator	✅	❌	❌	❌
Agent-driven CLI with JSON output	✅	—	—	—

Examples

Lint the graphify skill packs (a cross-agent skill distributor):

# Claude Code variant
agent-skills-lint --flavor claude lint ~/path/to/graphify/skill.md

# Codex variant
agent-skills-lint --flavor codex lint ~/path/to/graphify/skill-codex.md

# Kiro variant (no `trigger` field allowed)
agent-skills-lint --flavor kiro lint ~/path/to/graphify/skill-kiro.md

Install a remote skill directly from a URL:

agent-skills-lint install https://raw.githubusercontent.com/some/repo/main/skill.md

Regenerate your ~/.claude/CLAUDE.md index after adding a new skill:

agent-skills-lint index --dir ~/.claude/skills --to ~/.claude/CLAUDE.md --write

Roadmap

• Auto-fix mode (lint --fix) for common issues (rename-to-match-filename, description trimming)
• GitHub Action that lints skills on every PR in a skills repo
• Registry-aware install (agent-skills-lint install @npm-scope/skill-name)
• Publish skill schemas as JSON Schema for editor validation

Contributing

See CONTRIBUTING.md.

License

MIT