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

| Rule | Checks | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | skills/valid-frontmatter | Valid YAML, required name and description, field lengths and types, naming syntax, XML tags, and reserved names | | skills/name-matches-directory | Frontmatter name matches the directory containing SKILL.md | | skills/no-duplicate-skill-name | Frontmatter name is unique across all configured skill roots | | skills/no-empty-skill-body | SKILL.md includes instructions after its frontmatter | | skills/skill-index-budget | Combined name and description size across all skills stays within a configurable character budget | | skills/max-skill-lines | SKILL.md stays within a configurable line limit, defaulting to 200 | | skills/no-broken-local-references | Relative Markdown references resolve to an existing file or directory, scoped to the skill directory by default | | skills/long-reference-has-toc | Long referenced text files provide a linked table of contents near the top | | skills/no-deep-references | Relative Markdown links, images, and definitions point no deeper than one directory below SKILL.md, scoped to the skill directory by default | | skills/no-windows-paths | Relative Markdown reference targets use forward slashes, not Windows-style backslashes | | skills/description-third-person | description is written in the third person, not first or second person | | skills/no-unknown-frontmatter-fields | Frontmatter has no fields outside the specification and Claude Code's documented extensions (opt-in; not in the recommended preset) |

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

The Nix development shell provides Node.js 24 LTS and Vite+, which selects the pinned pnpm toolchain for the project:

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

License

MIT