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