eslint-plugin-copilot

ESLint plugin for linting GitHub Copilot repository customization files such as:

• .github/copilot-instructions.md
• .github/instructions/copilot-instructions.md
• .github/instructions/**/*.instructions.md
• .github/prompts/**/*.prompt.md
• .github/agents/**/*.agent.md
• .github/chatmodes/**/*.chatmode.md
• AGENTS.md, CLAUDE.md, and GEMINI.md

The plugin focuses on repository setup quality, metadata correctness, and modern GitHub Copilot customization conventions.

Table of contents

1. Installation
2. Quick start
3. What the presets lint
4. Presets
5. Rules
6. Contributors ✨

Installation

npm install --save-dev eslint-plugin-copilot eslint @eslint/markdown @eslint/json

Compatibility

• Supported ESLint versions: 9.x and 10.x
• Config system: Flat Config only (eslint.config.*)
• Node.js runtime: >=22.0.0

Quick start

For direct use in an application or repository, use the self-contained presets:

import copilot from "eslint-plugin-copilot";

export default [...copilot.configs.recommended];

The shipped presets already configure:

• plugins.markdown via @eslint/markdown
• plugins.json via @eslint/json for repository hooks
• language: "markdown/gfm"
• language: "json/json" for .github/hooks/*.json
• Copilot customization file globs for repository instructions, path-specific instructions, prompt files, custom agents, legacy chat modes, skills, agent-instructions files, and repository hooks

Shareable configs that already register @eslint/markdown and @eslint/json should use the no-language-plugin variants after that registration instead:

import copilot from "eslint-plugin-copilot";
import sharedConfig from "your-shared-eslint-config";

export default [
 ...sharedConfig,
 ...copilot.configs["recommended-without-language-plugins"],
];

Those variants keep the same files, language, and copilot rule layers, but they do not register plugins.markdown or plugins.json. Use them only when an earlier matching flat config entry already registers markdown from @eslint/markdown and json from @eslint/json; otherwise ESLint cannot resolve language: "markdown/gfm" or language: "json/json".

What the presets lint

The built-in presets target these Markdown file patterns:

• .github/copilot-instructions.md
• .github/instructions/copilot-instructions.md
• .github/instructions/**/*.instructions.md
• .github/prompts/**/*.prompt.md
• .github/agents/**/*.agent.md
• .github/chatmodes/**/*.chatmode.md
• .github/skills/**/*.md
• .claude/skills/**/*.md
• **/SKILL.md
• **/AGENTS.md
• **/CLAUDE.md
• **/GEMINI.md

They also target these JSON file patterns:

• .github/hooks/**/*.json

Presets

This plugin intentionally exports four presets:

Self-contained preset	No-language-plugin variant
🟢 copilot.configs.minimal	copilot.configs["minimal-without-language-plugins"]
🟡 copilot.configs.recommended	copilot.configs["recommended-without-language-plugins"]
🔴 copilot.configs.strict	copilot.configs["strict-without-language-plugins"]
🟣 copilot.configs.all	copilot.configs["all-without-language-plugins"]

Configuration examples by preset

import copilot from "eslint-plugin-copilot";

export default [
 ...copilot.configs.minimal,
 // ...copilot.configs.recommended,
 // ...copilot.configs.strict,
 // ...copilot.configs.all,
];

Rules

Rule	all	minimal	recommended	strict
no-blank-customization-body	✅	—	✅	✅
no-blank-repository-instructions	✅	—	✅	✅
no-blank-skill-body	✅	—	✅	✅
no-deprecated-agent-infer	✅	—	✅	✅
no-duplicate-agent-names	✅	—	✅	✅
no-duplicate-prompt-names	✅	—	✅	✅
no-duplicate-skill-names	✅	—	✅	✅
no-duplicate-slash-command-names	✅	—	✅	✅
no-empty-repository-hook-arrays	✅	—	—	✅
no-legacy-chatmode-files	✅	—	✅	✅
prefer-custom-instructions-under-code-review-limit	✅	—	—	✅
prefer-fast-repository-hooks	✅	—	—	✅
prefer-qualified-tools	✅	—	—	—
require-agent-tool-for-subagents	✅	—	✅	✅
require-agents-md-for-cross-surface-agent-instructions	✅	—	—	✅
require-chatmode-file-metadata	✅	✅	✅	✅
require-existing-agent-hook-cwd	✅	—	—	✅
require-existing-agent-mcp-servers	✅	—	—	✅
require-existing-relative-agent-links	✅	—	—	✅
require-existing-relative-instructions-links	✅	—	—	✅
require-existing-relative-prompt-links	✅	—	—	✅
require-existing-relative-skill-links	✅	—	—	✅
require-existing-repository-hook-cwd	✅	—	—	✅
require-github-copilot-target-for-mcp-servers	✅	—	✅	✅
require-instructions-apply-to	✅	✅	✅	✅
require-json-agent-mcp-servers	✅	—	✅	✅
require-prompt-file-metadata	✅	✅	✅	✅
require-qualified-agent-handoff-models	✅	—	✅	✅
require-relative-agent-hook-cwd	✅	—	✅	✅
require-relative-agent-links	✅	—	✅	✅
require-relative-instructions-links	✅	—	✅	✅
require-relative-prompt-links	✅	—	✅	✅
require-relative-repository-hook-cwd	✅	—	✅	✅
require-relative-skill-links	✅	—	✅	✅
require-repository-hook-arrays	✅	—	✅	✅
require-repository-hook-command-shell	✅	—	✅	✅
require-repository-hooks-object	✅	—	✅	✅
require-repository-instructions-file	✅	—	—	✅
require-skill-file-location	✅	—	✅	✅
require-skill-file-metadata	✅	—	✅	✅
require-skill-md-filename	✅	—	✅	✅
require-skill-name-match-directory	✅	—	—	✅
require-string-repository-hook-env-values	✅	—	✅	✅
require-valid-agent-argument-hint	✅	—	✅	✅
require-valid-agent-handoff-send	✅	—	✅	✅
require-valid-agent-handoffs	✅	—	✅	✅
require-valid-agent-hook-events	✅	—	✅	✅
require-valid-agent-hook-timeouts	✅	—	✅	✅
require-valid-agent-hooks	✅	—	✅	✅
require-valid-agent-invocation-controls	✅	—	✅	✅
require-valid-agent-mcp-servers	✅	—	✅	✅
require-valid-agent-model	✅	—	✅	✅
require-valid-agent-name	✅	—	✅	✅
require-valid-agent-subagents	✅	—	✅	✅
require-valid-agent-target	✅	—	✅	✅
require-valid-agent-tools	✅	—	✅	✅
require-valid-instructions-apply-to-globs	✅	—	✅	✅
require-valid-prompt-argument-hint	✅	—	✅	✅
require-valid-prompt-model	✅	—	✅	✅
require-valid-prompt-name	✅	—	✅	✅
require-valid-prompt-tools	✅	—	✅	✅
require-valid-repository-hook-command-type	✅	—	✅	✅
require-valid-repository-hook-env	✅	—	✅	✅
require-valid-repository-hook-events	✅	—	✅	✅
require-valid-repository-hook-timeouts	✅	—	✅	✅
require-valid-repository-hook-version	✅	—	✅	✅
require-valid-skill-directory-name	✅	—	✅	✅
require-valid-skill-license	✅	—	—	✅
require-valid-skill-name	✅	—	✅	✅

Contributors ✨

Thanks goes to these wonderful people (emoji key):