feat: add .github/copilot-instructions.md

[tmeschter]

Description

Adds a .github/copilot-instructions.md file that gives AI agents (Copilot, Cursor, Claude, etc.) the context they need to work effectively in this repo.

Covers:

• Repository layout — annotated directory tree
• Building — npm run build pipeline
• Versioning rules — NBGV, 0.0.0-placeholder convention, never manually edit versions
• Validating changes — token checks, frontmatter/reference validators, unit/trigger/integration tests
• Adding a new skill — step-by-step with version.json, frontmatter, tests/skills.json, test scaffolding
• Token limits — from .token-limits.json
• CI checks — table mapping CI jobs to local equivalents
• Commit/PR conventions — conventional titles for changelog generation
• Available agent skills — .github/skills/ table with invocation guidance

Every section was reviewed for agent relevance — human-only content (prerequisites, local Copilot CLI usage, marketplace publishing details) was excluded to keep the file focused and token-efficient.

Checklist

• Tests pass locally (cd tests && npm test)
• If modifying skill descriptions: verified routing correctness with integration tests (npm run test:skills:integration -- <skill>)
• If modifying skill USE FOR / DO NOT USE FOR / PREFER OVER clauses: confirmed no routing regressions for competing skills
• Version bumped in skill frontmatter (if skill files changed)

Related Issues

N/A — new file, no skill files changed.

[Copilot]

Pull request overview

Adds a repository-level instructions file intended to give AI agents enough context to contribute effectively (layout, build/versioning rules, validation/test commands, and skill authoring workflow).

Changes:

• Introduces .github/copilot-instructions.md with repo layout + build/versioning guidance.
• Documents local validation commands (tokens/frontmatter/references/tests) and maps CI checks to local equivalents.
• Provides a checklist-style “Adding a new skill” workflow and lists available repo-local agent skills.

Show a summary per file

File	Description
.github/copilot-instructions.md	New agent-facing repo instructions covering layout, build/versioning, validators/tests, CI mapping, and skill-authoring workflow.

Copilot's findings

Comments suppressed due to low confidence (3)

.github/copilot-instructions.md:171

• The "Plugin Version Check" CI row lists a behavioral reminder rather than an actionable local command. Since the repo has a dedicated script for this check, consider updating the local equivalent to something like running npm ci in scripts/ and npm run checkPluginVersionPr (at least when plugin/**/plugin.json changes).

| Plugin Version Check | `plugin.json` versions remain `0.0.0-placeholder` | Ensure you never edit version fields |
| Skill Tests | Unit and trigger tests for changed skills | `cd tests && npm test` |

.github/copilot-instructions.md:159

• The guidance about using folded YAML (>-) for long frontmatter descriptions conflicts with existing repo skill-authoring guidance: descriptions should be inline double-quoted strings, and >- is explicitly discouraged/unsupported (skills.sh incompatibility). Please update this line to match the repo convention (use description: "..." even when long, and keep it within the 1024-char limit).

- Use progressive disclosure: frontmatter → SKILL.md → references
- Descriptions over 200 chars in frontmatter must use folded YAML (`>-`)
- Markdown links must not escape the skill directory (validated by `npm run references`)

.github/copilot-instructions.md:168

• The local equivalent for the ESLint CI job is incomplete: CI runs typecheck+lint for both tests/ and scripts/, but the table only lists the tests/ commands. Update the local equivalent to include running npm run lint/npm run typecheck in scripts/ as well (or point to a single root command if preferred).

| ESLint | Linting + typechecking `scripts/` and `tests/` | `cd tests && npm run lint && npm run typecheck` |
| Token Analysis | Token counts and limits for markdown files | `npm run tokens check` |

• Files reviewed: 1/1 changed files
• Comments generated: 1

[Copilot]

The "Unit and Trigger Tests (from tests/)" section implies you can run cd tests && npm test directly, but the test suite reads skills from output/skills/ (git-ignored) and will fail unless you build first. Consider adding a note here (or prepend npm run build from repo root) so the instructions are correct for a fresh checkout.

This issue also appears in the following locations of the same file:

• line 157
• line 167
• line 170