oxlint-plugin-agent-skills

oxlint-plugin-agent-skills

Oxlint JavaScript plugin for validating the portable Agent Skills format and host-specific skill authoring conventions.

Set up with an agent

To let a coding agent (Claude Code, Codex, and so on) install and configure this plugin for you, paste this prompt:

Set up oxlint-plugin-agent-skills in this repository: install oxlint and oxlint-plugin-agent-skills as dev dependencies.
Read the installed docs locally — node_modules/oxlint-plugin-agent-skills/README.md for the Configure section, and node_modules/oxlint-plugin-agent-skills/src/rules/<rule>/README.md for each rule's options.
Register the plugin and its rules in the Oxlint configuration, then run Oxlint against a JavaScript or TypeScript file to confirm the skills rules report as expected.

Install

pnpm add -D oxlint oxlint-plugin-agent-skills

Configure

{
	"jsPlugins": ["oxlint-plugin-agent-skills"],
	"rules": {
		"skills/valid-frontmatter": "error",
		"skills/name-matches-directory": "error",
		"skills/no-duplicate-skill-name": "error",
		"skills/no-empty-skill-body": "error",
		"skills/skill-index-budget": ["warn", { "maxCharacters": 20000 }],
		"skills/max-skill-lines": ["warn", { "maxLines": 200 }],
		"skills/no-broken-local-references": "error",
		"skills/long-reference-has-toc": "warn",
		"skills/no-deep-references": "warn",
		"skills/no-windows-paths": "warn",
		"skills/description-third-person": "warn",
		// Opt-in: stricter than this plugin's default leniency.
		"skills/no-unknown-frontmatter-fields": "off",
	},
}

This plugin registers its rules under the skills namespace, so each rule is referenced as skills/<rule> regardless of the package name.

By default, each rule scans these paths relative to the Oxlint working directory:

• .agent/skills
• .agents/skills
• .claude/skills
• agents/skills
• skills

These are compatibility roots for different agent hosts. Claude Code natively scans .claude/skills for project-level skills, and Codex natively scans .agents/skills from the current working directory up to the repository root; the other defaults do not imply native discovery support for either host.

Set the roots rule option to scan other locations, or to restrict scanning to specific hosts' directories — for example only Codex's .agents/skills and Claude Code's .claude/skills:

{
	"rules": {
		"skills/valid-frontmatter": [
			"error",
			{
				"roots": [".agents/skills", ".claude/skills"],
			},
		],
	},
}

Apply the same roots option to each enabled rule that should inspect a custom location.

Rules

Index budgets are host-dependent. Codex uses at most 2% of the model context window for its initial skill list, or 8,000 characters when the context window is unknown. Projects targeting that fallback can configure skill-index-budget with { "maxCharacters": 8000 }; other hosts can retain or choose a different explicit budget.

Diagnostics are attached to the JavaScript or TypeScript file Oxlint is visiting, while each message starts with the actual SKILL.md path and line:

.agents/skills/example/SKILL.md:2 Frontmatter requires a description field.

Oxlint does not currently pass Markdown files to JavaScript plugins. Run Oxlint against at least one JavaScript or TypeScript file so the plugin can scan the configured skill roots.

Design requirements

The rule requirements map the portable Agent Skills specification and platform-specific Claude and Codex guidance to current and proposed lint rules.

Sources

• Agent Skills specification
• Claude skill authoring best practices
• Codex Agent Skills guide
• OpenAI skill examples
• Codex 220-line skill read analysis
• Codex CLI SKILL.md reading depth: empirical findings
• Oxlint JavaScript plugins

GitHub Sponsors

Development

nix develop
vp install --frozen-lockfile
vp run check

License

MIT