eslint-plugin-copilot 1.0.5

package/dist/rules/require-valid-skill-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-valid-skill-name.js","sourceRoot":"","sources":["../../src/rules/require-valid-skill-name.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,YAAY,EACZ,sBAAsB,GACzB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EACH,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACH,8BAA8B,EAC9B,qBAAqB,GACxB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,yBAAyB,GAAsB,iBAAiB,CAAC;IACnE,MAAM,CAAC,OAAO;QACV,OAAO,8BAA8B,CAAC,GAAG,EAAE;YACvC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACrC,OAAO;YACX,CAAC;YAED,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAEhE,IACI,WAAW,KAAK,IAAI;gBACpB,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC,EAC3C,CAAC;gBACC,OAAO;YACX,CAAC;YAED,MAAM,SAAS,GAAG,oBAAoB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YAE5D,IACI,SAAS,KAAK,SAAS;gBACvB,sBAAsB,CAClB,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,CAC9C,EACH,CAAC;gBACC,OAAO;YACX,CAAC;YAED,qBAAqB,CAAC,OAAO,EAAE;gBAC3B,IAAI,EAAE;oBACF,IAAI,EAAE,SAAS,IAAI,SAAS;iBAC/B;gBACD,SAAS,EAAE,kBAAkB;aAChC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;IACD,cAAc,EAAE,EAAE;IAClB,IAAI,EAAE;QACF,UAAU,EAAE,KAAK;QACjB,IAAI,EAAE;YACF,cAAc,EAAE;gBACZ,6BAA6B;gBAC7B,wBAAwB;gBACxB,qBAAqB;aACxB;YACD,WAAW,EACP,+FAA+F;YACnG,MAAM,EAAE,KAAK;YACb,WAAW,EAAE,IAAI;YACjB,oBAAoB,EAAE,KAAK;SAC9B;QACD,QAAQ,EAAE;YACN,gBAAgB,EACZ,+GAA+G;SACtH;QACD,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,SAAS;KAClB;IACD,IAAI,EAAE,0BAA0B;CACnC,CAAC,CAAC;AAEH,eAAe,yBAAyB,CAAC"}

package/docs/rules/getting-started.md

@@ -0,0 +1,24 @@
+# Getting started
+
+`eslint-plugin-copilot` helps teams lint GitHub Copilot customization files in a repository-friendly way.
+
+## Supported file types
+
+- repository-wide instructions: `.github/copilot-instructions.md`
+- path-specific instructions: `.github/instructions/**/*.instructions.md`
+- reusable prompts: `.github/prompts/**/*.prompt.md`
+- custom agents: `.github/agents/**/*.agent.md`
+- legacy chat modes: `.github/chatmodes/**/*.chatmode.md`
+- skill definitions and supporting Markdown: `.github/skills/**/*.md`, `.claude/skills/**/*.md`
+- agent instruction files: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
+- repository hook configs: `.github/hooks/**/*.json`
+
+## Basic setup
+
+```js
+import copilot from "eslint-plugin-copilot";
+
+export default [...copilot.configs.recommended];
+```
+
+The preset already configures Markdown support for Copilot content files, JSON support for repository hooks, and the documented file globs for supported Copilot customization assets.

package/docs/rules/guides/copilot-customization-files.md

@@ -0,0 +1,17 @@
+# Copilot customization files
+
+GitHub Copilot repository customization spans these markdown-first surfaces:
+
+- repository instructions
+- path-specific instructions
+- prompt files
+- custom agents
+- legacy chat modes
+- agent instruction files
+- skill definition files
+
+It also includes repository hook configuration files under `.github/hooks/*.json`.
+
+This plugin intentionally keeps its first rule set focused on structural correctness and metadata quality for those files.
+
+That includes modern custom-agent details such as deprecated frontmatter cleanup, subagent/tool wiring checks, valid subagent allow-list metadata, valid invocation-control flags, valid target values, valid `tools` list metadata, valid `mcp-servers` list metadata, handoff metadata integrity, valid handoff send values, qualified handoff model names, valid model override metadata, valid agent-scoped hook commands, supported hook event names, numeric hook timeouts, repository-relative hook working directories, GitHub-target-specific agent metadata, prompt-body relative-link checks, valid prompt-model metadata, prompt and agent naming hygiene, skill location and frontmatter requirements, skill naming and link rules, repository hook JSON schema validation, repository hook path and environment checks, body-content quality checks, and migration guidance away from legacy chatmode files, not just basic required metadata.

package/docs/rules/no-blank-customization-body.md

@@ -0,0 +1,52 @@
+# no-blank-customization-body
+
+Disallow blank bodies in Copilot customization files other than repository-wide instructions.
+
+> **Rule catalog ID:** R009
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+- `.github/prompts/**/*.prompt.md`
+- `.github/agents/**/*.agent.md`
+- `.github/chatmodes/**/*.chatmode.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+
+## What this rule reports
+
+- Copilot customization files whose body is empty after ignoring frontmatter, whitespace, and HTML comments
+- files that only contain metadata without any meaningful Markdown instructions in the document body
+
+## Why this rule exists
+
+Copilot customization files are instruction surfaces. A prompt, custom agent, or path-specific instructions file that only contains frontmatter does not give Copilot any actual guidance to apply. This rule catches metadata-only files before they silently become ineffective customization points.
+
+Repository-wide `.github/copilot-instructions.md` is intentionally excluded because it already has a dedicated blank-content rule.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review the repository
+agent: ask
+---
+<!-- no actual prompt body -->
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review the repository
+agent: ask
+---
+Review the repository for configuration drift and summarize the biggest risks first.
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+- [VS Code Docs: Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)

package/docs/rules/no-blank-repository-instructions.md

@@ -0,0 +1,37 @@
+# no-blank-repository-instructions
+
+Disallow empty repository-wide Copilot instructions files.
+
+> **Rule catalog ID:** R004
+
+## Targeted pattern scope
+
+- `.github/copilot-instructions.md`
+
+## What this rule reports
+
+- repository-wide instructions files whose visible body content is blank after trimming comments and whitespace
+
+## Why this rule exists
+
+GitHub Copilot repository instructions are the baseline customization surface for a repository. An empty `.github/copilot-instructions.md` file communicates intent to customize Copilot, but it provides no usable guidance.
+
+## ❌ Incorrect
+
+```md
+<!-- placeholder -->
+```
+
+## ✅ Correct
+
+```md
+# Repository guidance
+
+- Prefer Flat Config for ESLint.
+- Run `npm test` before proposing changes.
+- Keep prompt files in `.github/prompts/` and path-specific instructions in `.github/instructions/`.
+```
+
+## Further reading
+
+- [GitHub Docs: Add repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)

package/docs/rules/no-blank-skill-body.md

@@ -0,0 +1,41 @@
+# no-blank-skill-body
+
+Disallow blank Copilot skill definition bodies.
+
+> **Rule catalog ID:** R047
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- skill files whose Markdown body is empty after frontmatter
+
+## Why this rule exists
+
+A skill without any instructions, examples, or guidance provides almost no value. The frontmatter can identify the skill, but the body is where the actual reusable task knowledge lives.
+
+## ❌ Incorrect
+
+```md
+---
+name: review-checklist
+description: Review code changes with the repository checklist.
+---
+```
+
+## ✅ Correct
+
+```md
+---
+name: review-checklist
+description: Review code changes with the repository checklist.
+---
+Follow the review checklist, call out risk areas, and summarize required follow-up work.
+```
+
+## Further reading
+
+- [GitHub Docs: About agent skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)

package/docs/rules/no-deprecated-agent-infer.md

@@ -0,0 +1,42 @@
+# no-deprecated-agent-infer
+
+Disallow deprecated `infer` frontmatter in Copilot custom agent files.
+
+> **Rule catalog ID:** R007
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- custom agent files that still declare deprecated `infer` frontmatter
+
+## Why this rule exists
+
+VS Code custom agents now use `user-invocable` and `disable-model-invocation` for picker visibility and subagent invocation control. Keeping deprecated `infer` metadata around makes agent behavior less explicit and drifts away from the current contract.
+
+## ❌ Incorrect
+
+```md
+---
+description: Hidden implementation helper
+infer: false
+---
+Implement changes based on the approved plan.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Hidden implementation helper
+user-invocable: false
+disable-model-invocation: false
+---
+Implement changes based on the approved plan.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/no-duplicate-agent-names.md

@@ -0,0 +1,36 @@
+# no-duplicate-agent-names
+
+Disallow duplicate effective custom-agent names across workspace custom-agent files.
+
+> **Rule catalog ID:** R039
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- agent files whose effective `name` collides with another agent file in `.github/agents`
+- collisions involving explicit `name` frontmatter and filename-derived default names
+
+## Why this rule exists
+
+Custom agents are easier to select and reason about when each one has a unique effective name. Duplicate names make agent routing and documentation more confusing than necessary.
+
+## ❌ Incorrect
+
+```text
+.github/agents/reviewer.agent.md
+.github/agents/other.agent.md   # with frontmatter: name: reviewer
+```
+
+## ✅ Correct
+
+```text
+.github/agents/reviewer.agent.md
+.github/agents/other.agent.md   # with frontmatter: name: reviewer-security
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/no-duplicate-prompt-names.md

@@ -0,0 +1,36 @@
+# no-duplicate-prompt-names
+
+Disallow duplicate effective prompt names across workspace prompt files.
+
+> **Rule catalog ID:** R038
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- prompt files whose effective `name` collides with another prompt file in `.github/prompts`
+- collisions involving explicit `name` frontmatter and filename-derived default names
+
+## Why this rule exists
+
+Prompt files share a slash-command namespace. Duplicate effective names make it ambiguous which prompt a caller intends to invoke and can create hard-to-diagnose behavior differences across tools.
+
+## ❌ Incorrect
+
+```text
+.github/prompts/review.prompt.md
+.github/prompts/other.prompt.md   # with frontmatter: name: review
+```
+
+## ✅ Correct
+
+```text
+.github/prompts/review.prompt.md
+.github/prompts/other.prompt.md   # with frontmatter: name: review-security
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/no-duplicate-skill-names.md

@@ -0,0 +1,37 @@
+# no-duplicate-skill-names
+
+Disallow duplicate effective skill names across project skill definition files.
+
+> **Rule catalog ID:** R054
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- skill definitions with duplicate effective names across `.github/skills` and `.claude/skills`
+- collisions involving explicit frontmatter names and directory-derived default names
+
+## Why this rule exists
+
+Duplicate skill names make it harder to understand which skill a repository intends to expose for a given task. Keeping skill names unique also avoids confusion when skills are documented or referenced externally.
+
+## ❌ Incorrect
+
+```text
+.github/skills/review/SKILL.md
+.claude/skills/review-clone/SKILL.md   # with frontmatter: name: review
+```
+
+## ✅ Correct
+
+```text
+.github/skills/review/SKILL.md
+.claude/skills/review-clone/SKILL.md   # with frontmatter: name: review-clone
+```
+
+## Further reading
+
+- [GitHub Docs: About agent skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)

package/docs/rules/no-duplicate-slash-command-names.md

@@ -0,0 +1,40 @@
+# no-duplicate-slash-command-names
+
+Disallow duplicate slash-command names across prompt files and skills.
+
+> **Rule catalog ID:** R069
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- prompt names that collide with skill names
+- skill names that collide with prompt names
+- collisions involving explicit frontmatter names and default filename or directory-derived names
+
+## Why this rule exists
+
+Prompt files and skills both participate in slash-command style invocation flows. Reusing the same effective command name across those surfaces creates namespace collisions and makes command selection ambiguous.
+
+## ❌ Incorrect
+
+```text
+.github/prompts/review.prompt.md   # effective name: review
+.github/skills/review/SKILL.md     # effective name: review
+```
+
+## ✅ Correct
+
+```text
+.github/prompts/review.prompt.md         # effective name: review
+.github/skills/review-checklist/SKILL.md # effective name: review-checklist
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
+- [GitHub Docs: Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills)

package/docs/rules/no-empty-repository-hook-arrays.md

@@ -0,0 +1,44 @@
+# no-empty-repository-hook-arrays
+
+Disallow empty repository hook arrays that opt into an event without any hook definitions.
+
+> **Rule catalog ID:** R067
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook event arrays declared as `[]`
+
+## Why this rule exists
+
+An empty array says the repository opted into a hook event but did not actually configure any hooks. Removing empty event entries keeps the file focused on real behavior and makes the configuration easier to read.
+
+## ❌ Incorrect
+
+```json
+{ "version": 1, "hooks": { "sessionStart": [] } }
+```
+
+## ✅ Correct
+
+```json
+{ "version": 1, "hooks": {} }
+```
+
+or:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready" }]
+  }
+}
+```
+
+## Further reading
+
+- [GitHub Docs: Using hooks with GitHub Copilot agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)

package/docs/rules/no-legacy-chatmode-files.md

@@ -0,0 +1,53 @@
+# no-legacy-chatmode-files
+
+Disallow legacy Copilot `.chatmode.md` files in favor of modern `.agent.md` custom agents.
+
+> **Rule catalog ID:** R011
+
+## Targeted pattern scope
+
+- `.github/chatmodes/**/*.chatmode.md`
+
+## What this rule reports
+
+- legacy workspace chat mode files that still use the old `.chatmode.md` naming and location
+
+## Why this rule exists
+
+VS Code custom agents replaced legacy chat modes. The current documentation recommends migrating older `.chatmode.md` files to `.agent.md` files under `.github/agents/` so repositories use the modern Copilot customization surface.
+
+Keeping legacy chat mode files around makes repository customization harder to standardize and pushes teams toward an older contract that VS Code now documents as migrated terminology.
+
+## ❌ Incorrect
+
+```md
+---
+description: Plan work carefully
+---
+Plan the requested change before implementation.
+```
+
+Saved as:
+
+```text
+.github/chatmodes/planner.chatmode.md
+```
+
+## ✅ Correct
+
+```md
+---
+description: Plan work carefully
+---
+Plan the requested change before implementation.
+```
+
+Saved as:
+
+```text
+.github/agents/planner.agent.md
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/overview.md

@@ -0,0 +1,27 @@
+# Rule overview
+
+`eslint-plugin-copilot` focuses on repository customization quality for GitHub Copilot.
+
+## What the rules cover
+
+- required frontmatter metadata for prompt, instructions, custom-agent, chatmode, and skill definition files
+- non-empty, correctly shaped optional metadata such as prompt and agent `name`, `argument-hint`, `tools`, `model`, and skill `license`
+- repository-relative `applyTo` glob validation for path-specific instructions
+- practical repository-instructions guidance such as the code-review 4,000-character budget
+- baseline repository setup when you opt into prompts, custom agents, chat modes, skills, agent instruction files, or path-specific instructions
+- duplicate effective names across prompts, custom agents, skills, and shared slash-command namespaces
+- relative-link and existing-target checks for prompts, instructions, agents, and skills
+- modern custom-agent-only metadata such as subagent wiring, invocation controls, targets, MCP servers, hooks, and handoffs
+- GitHub-target-specific custom-agent metadata such as `mcp-servers` targeting and JSON config references
+- repository-relative and existing-path validation for agent hook `cwd` values
+- repository hook JSON schema quality under `.github/hooks/*.json`, including `version`, `hooks`, event arrays, hook `type`, shell commands, `cwd`, `timeoutSec`, and `env`
+- repository hook maintainability checks such as avoiding empty event arrays and oversized timeout budgets
+- migration pressure away from legacy `.chatmode.md` customization files toward modern `.agent.md` agents
+- modern fully-qualified `tools` metadata in prompt, custom agent, and legacy chat mode files
+
+## Design goals
+
+- reflect documented GitHub Copilot and VS Code customization conventions
+- keep rules static and predictable
+- favor setup correctness over speculative content policing
+- work directly on markdown-first Copilot asset files plus repository hook JSON

package/docs/rules/prefer-custom-instructions-under-code-review-limit.md

@@ -0,0 +1,39 @@
+# prefer-custom-instructions-under-code-review-limit
+
+Prefer repository and path-specific Copilot instruction files to stay within the 4,000-character code-review instruction budget.
+
+> **Rule catalog ID:** R036
+
+## Targeted pattern scope
+
+- `.github/copilot-instructions.md`
+- `.github/instructions/**/*.instructions.md`
+
+## What this rule reports
+
+- repository or path-specific instruction files whose raw character length exceeds 4,000 characters
+
+## Why this rule exists
+
+GitHub documents that code review only considers roughly the first 4,000 characters of custom instructions. Keeping instruction files within that budget reduces the chance that important guidance is silently ignored during review flows.
+
+## ❌ Incorrect
+
+```md
+<!-- imagine thousands of characters of guidance here -->
+# Review policy
+
+...very long instructions document...
+```
+
+## ✅ Correct
+
+```md
+# Review policy
+
+Keep review instructions focused, high-signal, and short enough that the whole file fits within the code-review instruction budget.
+```
+
+## Further reading
+
+- [GitHub Docs: Add repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)

package/docs/rules/prefer-fast-repository-hooks.md

@@ -0,0 +1,43 @@
+# prefer-fast-repository-hooks
+
+Prefer repository hooks to stay at or below the default 30-second timeout unless a slower hook is truly necessary.
+
+> **Rule catalog ID:** R068
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook `timeoutSec` values greater than the documented default 30-second timeout budget
+
+## Why this rule exists
+
+Long-running hooks slow down agent workflows and increase the chance of timeouts or poor user experience. Keeping hooks within the default budget encourages lightweight, reliable automation.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "timeoutSec": 120 }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "timeoutSec": 10 }]
+  }
+}
+```
+
+## Further reading
+
+- [GitHub Docs: Using hooks with GitHub Copilot agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)

package/docs/rules/prefer-qualified-tools.md

@@ -0,0 +1,49 @@
+# prefer-qualified-tools
+
+Prefer fully-qualified tool names in Copilot prompt files, custom agents, and legacy chat modes.
+
+> **Rule catalog ID:** R006
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+- `.github/agents/**/*.agent.md`
+- `.github/chatmodes/**/*.chatmode.md`
+
+## What this rule reports
+
+- entries in `tools` frontmatter arrays that are not fully qualified with a provider or namespace segment
+- except for documented built-in subagent tools such as `agent` and `runSubagent`
+
+## Why this rule exists
+
+Modern Copilot tooling supports fully-qualified tool names such as `search/codebase` to reduce ambiguity between built-in tools, extension-provided tools, and MCP tools.
+
+The built-in `agent` and `runSubagent` tools are exceptions because current VS Code subagent documentation refers to those aliases directly when enabling subagent orchestration.
+
+## ❌ Incorrect
+
+```md
+---
+description: Release notes helper
+agent: agent
+tools: [file_search, fetch]
+---
+Generate release notes for the latest changes.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Release notes helper
+agent: agent
+tools: [search/file_search, fetch/fetch]
+---
+Generate release notes for the latest changes.
+```
+
+## Further reading
+
+- [VS Code Docs: Reusable prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)