chore: set up shared agent tooling (Copilot + Claude Code)#416
Open
jalezi wants to merge 4 commits into
Open
Conversation
Add cross-tool agent configuration so Copilot, Claude Code, and other agents share one source of truth: - Add canonical agent guidance (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .github/instructions/) and Copilot custom agents under .github/agents/. - Keep reusable skills in .agents/skills/ as the canonical location; mirror them to .claude/skills/ (Claude Code's discovery path) via a `yarn sync-skills` script wired into postinstall. The generated copy is git-ignored. - Drop the pinned `model` field from .github/agents/*.agent.md so each agent inherits the contributor's selected Copilot model, avoiding availability and naming-format issues across plans/clients. - Document the skills sync workflow in README.md and AGENTS.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jalezi
added
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR centralizes AI coding-agent guidance for the Podnebnik repository by introducing a single canonical instruction set and a shared, tool-neutral skills library, with mirroring for tools that require alternate discovery paths.
Changes:
- Adds canonical, repository-wide agent instructions plus domain-specific instruction overlays under
.github/instructions/. - Introduces vendor-neutral reusable skills under
.agents/skills/and sync tooling to generate a git-ignored.claude/skills/mirror. - Adds Copilot Coding Agent environment setup workflow and supporting documentation updates.
Reviewed changes
Copilot reviewed 23 out of 24 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| skills-lock.json | Adds a lock file for externally sourced skills (currently empty). |
| README.md | Documents canonical skill location and the yarn sync-skills workflow. |
| package.json | Adds sync-skills script and runs it in postinstall. |
| CLAUDE.md | Points Claude Code at shared agent instructions via AGENTS.md. |
| AGENTS.md | Establishes .github/copilot-instructions.md as canonical guidance and documents skill mirroring. |
| .gitignore | Ignores generated .claude/skills mirror output. |
| .github/workflows/copilot-setup-steps.yml | Adds a Copilot setup workflow to provision repo dependencies and run typecheck/build. |
| .github/instructions/typescript-solid-eleventy.instructions.md | Adds frontend/TS/Solid/Eleventy-specific instruction overlay (issue noted in review comment). |
| .github/instructions/testing.instructions.md | Adds testing/validation standards overlay. |
| .github/instructions/security.instructions.md | Adds security standards overlay. |
| .github/instructions/performance.instructions.md | Adds performance standards overlay. |
| .github/instructions/documentation.instructions.md | Adds documentation/content standards overlay. |
| .github/instructions/code-review.instructions.md | Adds code review standards overlay. |
| .github/copilot-instructions.md | Adds the canonical repository-wide agent guidance. |
| .github/agents/software-engineer.agent.md | Adds a Copilot custom agent definition for implementation work. |
| .github/agents/reviewer.agent.md | Adds a Copilot custom agent definition for PR review. |
| .github/agents/debugger.agent.md | Adds a Copilot custom agent definition for debugging. |
| .github/agents/architect.agent.md | Adds a Copilot custom agent definition for architecture planning. |
| .agents/skills/write-tests/SKILL.md | Adds a reusable “write-tests” skill. |
| .agents/skills/setup-component/SKILL.md | Adds a reusable “setup-component” skill. |
| .agents/skills/refactor-code/SKILL.md | Adds a reusable “refactor-code” skill. |
| .agents/skills/generate-docs/SKILL.md | Adds a reusable “generate-docs” skill. |
| .agents/skills/debug-issue/SKILL.md | Adds a reusable “debug-issue” skill. |
| .agents/skills/code-review/SKILL.md | Adds a reusable “code-review” skill. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
TypeScript 6.x treats `baseUrl` as a hard error (TS5101); it stops functioning entirely in 7.0. The Copilot Setup Steps workflow runs `yarn typecheck` with a fresh install that resolves typescript ^6.0.3, which failed on this option. Under `moduleResolution: "bundler"`, the `paths` mappings resolve relative to this config without `baseUrl`, so removing it is behavior- preserving. Prefer this over `ignoreDeprecations: "6.0"` because that value is rejected by TS 5.x and only defers the break to 7.0. Verified `tsc --noEmit` passes on both TS 5.9 and 6.x. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
applyTo is a single glob string containing comma-separated patterns. In standard glob matching, the commas outside of a brace expansion are treated as literal characters, so this will likely match no files (and the instruction won’t apply where intended). Use a YAML list (as in the other instruction files in this PR) or a single brace-expanded glob that doesn’t include literal commas. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
Author
|
Superseded by #418. |
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
We want every coding agent that touches this repo — GitHub Copilot, Claude Code, and others — to follow the same project guidance and reuse the same skills, instead of each tool having its own divergent config. This PR establishes one tool-neutral source of truth for agent behavior.
The agent definitions, instructions, and skills in this PR were bootstrapped using the github-copilot-starter skill from
github/awesome-copilot, then adapted to Podnebnik's stack and conventions.What
Canonical guidance (tool-neutral)
AGENTS.mdandCLAUDE.mdboth resolve to.github/copilot-instructions.mdas the single canonical instruction file, so Copilot and Claude Code read identical guidance..github/instructions/— domain-specific guidance (TypeScript/Solid/Eleventy, testing, security, documentation, performance, code review).Copilot custom agents —
.github/agents/(architect, debugger, reviewer, software-engineer).model:field from each agent. The field is optional; when omitted, each agent inherits the contributor's selected Copilot model. Pinning"Claude Sonnet 4"was fragile — it depends on the model being enabled for the contributor's plan + org policy, used a display-name format rather than the documented slug form, and parses inconsistently across Copilot clients (copilot-cli#2133, #1195). See Microsoft Learn — custom agents.Reusable skills —
.agents/skills/(code-review, debug-issue, generate-docs, refactor-code, setup-component, write-tests)..agents/skills/is the canonical, vendor-neutral location..claude/skills/, so we mirror the canonical skills there via a newyarn sync-skillsscript wired intopostinstall. The generated copy is git-ignored to keep a single source of truth.skills-lock.jsontracks externally-sourced skills (currently empty after pruning the unused starter skill).Tooling & docs
.github/workflows/copilot-setup-steps.yml— Copilot coding agent environment setup.README.md+AGENTS.mddocument the skills sync workflow (edit in.agents/skills/, runyarn sync-skills).Notes for reviewers
.claude/skills/is intentionally absent from the diff (git-ignored, generated byyarn sync-skills/yarn install).🤖 Generated with Claude Code