From b30566e5117cdf6b96dc77ac9c6f3d30211bf503 Mon Sep 17 00:00:00 2001 From: devantler <26203420+devantler@users.noreply.github.com> Date: Sun, 12 Jul 2026 06:56:21 +0000 Subject: [PATCH] chore(deps): update agent skills --- .../skills/agent-instructions/SKILL.md | 132 ++++++++++-------- .../skills/conventional-release/SKILL.md | 8 +- .../skills/ways-of-working/SKILL.md | 6 +- 3 files changed, 80 insertions(+), 66 deletions(-) diff --git a/plugins/agentic-engineering/skills/agent-instructions/SKILL.md b/plugins/agentic-engineering/skills/agent-instructions/SKILL.md index 331b907..fc53099 100644 --- a/plugins/agentic-engineering/skills/agent-instructions/SKILL.md +++ b/plugins/agentic-engineering/skills/agent-instructions/SKILL.md @@ -1,28 +1,30 @@ --- -description: Architect a repository's AI-agent instruction files so one canonical source drives every tool without drift — AGENTS.md as the cross-tool source of truth, thin per-tool shims (CLAUDE.md, GEMINI.md) that include it, and a concise review-focused .github/copilot-instructions.md subset. Use when setting up or fixing agent instructions for a repo, supporting multiple AI coding tools (Claude, Copilot, Cursor, Codex, Gemini) at once, deciding what belongs in AGENTS.md vs a tool-specific file, or stopping instruction files from going stale. +description: Architect a repository's AI-agent instruction files so one canonical source drives every tool without drift — AGENTS.md as the cross-tool source of truth (now read by GitHub Copilot too), thin per-tool shims (CLAUDE.md, GEMINI.md) that include it, and optional path-scoped .github/instructions/ rules. Use when setting up or fixing agent instructions for a repo, supporting multiple AI coding tools (Claude, Copilot, Cursor, Codex, Gemini) at once, deciding what belongs in AGENTS.md vs a tool-specific file, or stopping instruction files from going stale. license: Apache-2.0 metadata: github-path: agent-instructions - github-ref: refs/tags/v1.4.0 + github-ref: refs/tags/v1.5.0 github-repo: https://github.com/devantler-tech/agent-skills - github-tree-sha: e7cfc6976a5f195340587e87211c5eda55307f37 + github-tree-sha: ede64b81b2c321ce9680f852ed5f743ac28a04da name: agent-instructions --- # Agent Instructions -Most AI coding tools read project guidance from a file in the repo — but each looks in a +Most AI coding tools read project guidance from a file in the repo — historically each looked in a *different* place (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, …). Copy the same guidance into each one and the copies **drift**: a command changes in one file and the others keep telling agents the old way. The fix is one **canonical** source plus thin tool-specific **shims** -(which include the canonical file) and the occasional deliberate **subset** (for a tool that can't -read the canonical file). Keep all durable guidance in the canonical file; keep only genuine -tool-specific quirks in a tool's own file. +(which include the canonical file). Keep all durable guidance in the canonical file; keep only +genuine tool-specific quirks in a tool's own file. + +The good news: `AGENTS.md` is now read by nearly every major tool — **including GitHub Copilot** — so +the "one canonical file" ideal is finally achievable without a per-tool copy. ## The canonical file: `AGENTS.md` -`AGENTS.md` is the emerging cross-tool standard — a plain-Markdown file at the repo root, read -natively by a growing set of agents and editors (e.g. Codex and Cursor). Make it the **single -source of truth** for everything durable and tool-neutral: +`AGENTS.md` is the cross-tool standard — a plain-Markdown file at the repo root, read natively by a +growing set of agents and editors (Codex, Cursor, Gemini CLI, and GitHub Copilot). Make it the +**single source of truth** for everything durable and tool-neutral: - **What the project is** — one-paragraph purpose, the stack, where the important code lives. - **How to build, test, validate, and run** — the exact commands an agent should use (and which @@ -36,77 +38,89 @@ Write it **tool-neutral**: no "when you are Claude…" assumptions. Anything tru goes in that tool's file, not here. Keep it readable and scoped — an agent re-reads it every turn, so length is a cost. +**Nested `AGENTS.md`.** In a monorepo or a large sub-package, drop an `AGENTS.md` in the subdirectory: +tools that support the standard read the nearest one and let it **take precedence** over the root on +conflicts. Reach for this before a path-scoped tool-specific file when the guidance is itself +tool-neutral. + ## Map each tool to its file | Tool | File it reads | How to wire it | |---|---|---| -| Codex / Cursor / generic | `AGENTS.md` | Read natively — no shim needed. | +| Codex / Cursor / Gemini / generic | `AGENTS.md` | Read natively — no shim needed. | | Claude Code | `CLAUDE.md` | One-line **shim**: a single `@AGENTS.md` line (Claude expands `@`-includes), so there is one source, not two. | | Gemini CLI | `GEMINI.md` | Same shim approach — include `AGENTS.md` rather than duplicating it. | -| GitHub Copilot — coding agent / chat | `.github/copilot-instructions.md` (repo-wide) + `.github/instructions/**/*.instructions.md` (path-scoped via `applyTo:` globs) | Concise **subset** (see below). | -| GitHub Copilot — code review | `.github/copilot-instructions.md` + `.instructions.md` **only** | Same subset — and it does **not** read `AGENTS.md`. | - -**Shim vs. subset.** A *shim* (`CLAUDE.md`, `GEMINI.md`) just includes the canonical file, so it -never drifts and needs no upkeep. A *subset* (`.github/copilot-instructions.md`) is deliberately -*different* content because the consuming tool cannot read `AGENTS.md` — so it carries its own -maintenance burden (see *Keep them in sync*). - -## The Copilot gotcha - -GitHub Copilot is the case that breaks the "one canonical file" ideal, and it has **two distinct -consumers** with the same files but different limits: - -- Copilot **does not read `AGENTS.md`** — neither the coding agent nor code review. It reads - `.github/copilot-instructions.md` (repo-wide) and `.github/instructions/**/*.instructions.md` - (path-specific). -- Copilot **code review** in particular **truncates** the instructions past roughly **4000 - characters** — guidance beyond that point is silently ignored during review. - -So `.github/copilot-instructions.md` must be a **concise, review-focused subset** — short -imperative rules a reviewer applies (the bugs and conventions you most want caught), **not** a copy -of `AGENTS.md`. Keep it well under the limit. Use path-specific `.instructions.md` files (with an -`applyTo:` frontmatter glob) for rules that only apply to part of the tree, so each stays small. - -> **Anti-pattern:** consolidating `copilot-instructions.md` *into* `AGENTS.md` and deleting it to -> "remove duplication". Because Copilot can't read `AGENTS.md`, this silently removes all per-repo -> guidance from Copilot review and the coding agent. The duplication is the price of Copilot not -> supporting the standard — manage it (below), don't eliminate it. +| GitHub Copilot — code review | `AGENTS.md` | Read natively ([since 2026-06-18](https://github.blog/changelog/2026-06-18-copilot-code-review-agents-md-support-and-ui-improvements/)) — no separate file needed. | +| GitHub Copilot — coding agent / chat | `AGENTS.md` **plus** optional `.github/copilot-instructions.md` + `.github/instructions/**/*.instructions.md` | Reads `AGENTS.md`; an optional `copilot-instructions.md` adds always-on emphasis (see below). | + +**Shims need no upkeep.** A *shim* (`CLAUDE.md`, `GEMINI.md`) just includes the canonical file, so it +never drifts. Everything else reads `AGENTS.md` directly. + +## Copilot now reads `AGENTS.md` + +GitHub Copilot used to be the exception that forced a second file — it couldn't read `AGENTS.md`, so +you maintained a `.github/copilot-instructions.md`. **That is no longer true:** + +- Copilot **code review** reads `AGENTS.md` from the repo root + ([changelog, 2026-06-18](https://github.blog/changelog/2026-06-18-copilot-code-review-agents-md-support-and-ui-improvements/)). +- Copilot **coding agent** reads `AGENTS.md` too (root + nested, nearest-wins). + +So `AGENTS.md` alone now covers Copilot, and a separate `.github/copilot-instructions.md` is +**optional**, not required: + +- **Most repos can drop it** and rely on `AGENTS.md` — one canonical file, no subset to keep in sync. + Consolidating an existing `copilot-instructions.md` *into* `AGENTS.md` and deleting it is now a + legitimate simplification. (It used to silently strip Copilot's guidance, because Copilot couldn't + read `AGENTS.md`; that risk is gone.) +- **Keep one only for a concrete reason.** Copilot's coding agent treats `.github/copilot-instructions.md` + as always-on context, so a short file there can pin the few rules you want weighted highest. If you + keep it, make it a **concise subset** — short imperative rules, *not* a copy of `AGENTS.md`. Brevity + is what makes the emphasis work; a long always-on file dilutes it. (Copilot code review's old + ~4000-char instruction truncation was + [removed on 2026-06-12](https://github.blog/changelog/2026-06-12-copilot-code-review-new-configurations-and-controls/), + so length is an emphasis concern now, not a hard limit.) +- **Path-scoped rules** live in `.github/instructions/.instructions.md` (with an `applyTo:` + frontmatter glob) — guidance for only part of the tree (tests, infra, a sub-package). Useful with or + without a `copilot-instructions.md`; `excludeAgent: "code-review"` / `"copilot-coding-agent"` targets + one consumer. ## Keep them in sync (definition of done) -Shims (`CLAUDE.md`/`GEMINI.md` that `@`-include) never drift — that's their point. The Copilot -**subset** does drift, because it is hand-maintained separate content. So make it part of *done*: +Shims (`CLAUDE.md`/`GEMINI.md` that `@`-include) never drift — that's their point. If you keep **any** +hand-maintained second file (a Copilot subset, or a path-scoped `.instructions.md`), it *can* drift, +so make sync part of *done*: > A change that touches a command, flag, path, label, generated-file list, validation step, or > convention updates **every** instruction file that referenced it **in the same PR** — the -> `AGENTS.md` canonical text *and* the `copilot-instructions.md` / `.instructions.md` subset. +> `AGENTS.md` canonical text *and* any subset / path-scoped file. -Never let the canonical file and the Copilot subset describe the project differently. A stale -instruction file is worse than none: it actively misleads every future agent and reviewer. +A stale instruction file is worse than none: it actively misleads every future agent and reviewer. The +surest way never to go stale is a single `AGENTS.md` with no hand-maintained copies. ## Recipe: wire up a repo 1. **Write `AGENTS.md`** — the canonical, tool-neutral guidance (sections above). This is the bulk - of the work; everything else points back to it. + of the work; everything else points back to it. Codex, Cursor, Gemini, and Copilot read it directly. 2. **Add shims** for include-capable tools you support: - `CLAUDE.md` → a single line: `@AGENTS.md` - `GEMINI.md` → include `AGENTS.md` the same way. - Codex and Cursor need nothing — they read `AGENTS.md` directly. -3. **Add `.github/copilot-instructions.md`** — a concise (≤ ~4000 char) review-focused subset of the - most important, checkable rules. Short imperative bullets, not prose; not a dump of `AGENTS.md`. -4. **(Optional) Add path-specific `.github/instructions/.instructions.md`** with `applyTo:` - globs for rules that apply to only part of the tree (e.g. tests, infra, a sub-package). -5. **Record the sync rule** in `AGENTS.md` itself so future changes keep the subset current. +3. **(Optional) `.github/copilot-instructions.md`** — only if you want a few always-on rules weighted + highest for Copilot's coding agent; keep it a concise subset, not a dump of `AGENTS.md`. +4. **(Optional) `.github/instructions/.instructions.md`** with `applyTo:` globs for rules that + apply to only part of the tree (tests, infra, a sub-package). +5. **Record the sync rule** in `AGENTS.md` if you kept any hand-maintained second file. ## Pitfalls checklist - ❌ Duplicating full `AGENTS.md` content into `CLAUDE.md`/`GEMINI.md` — use a one-line include instead so there is a single source. -- ❌ Treating `copilot-instructions.md` as a copy of `AGENTS.md` — it is a focused subset; a copy - drifts and (for review) gets truncated. -- ❌ Letting `.github/copilot-instructions.md` grow past ~4000 chars — Copilot review silently drops - the overflow; split path-specific rules into `.instructions.md` files. -- ❌ Putting tool-specific assumptions in `AGENTS.md` — keep it neutral; quirks go in that tool's - file. -- ❌ Changing a command/path/convention in `AGENTS.md` without updating the Copilot subset in the - same PR — that is how the files go stale. +- ❌ Keeping a `.github/copilot-instructions.md` that just **duplicates** `AGENTS.md` — now that + Copilot reads `AGENTS.md`, a full copy is pure drift risk; drop it, or trim it to a small focused subset. +- ❌ Putting *new* canonical guidance in a kept `copilot-instructions.md` — durable rules belong in + `AGENTS.md`; a subset only re-emphasises a few of them. +- ❌ Letting any kept `.github/copilot-instructions.md` grow into a parallel rulebook — the old + ~4000-char review truncation is gone, but a long always-on file dilutes the emphasis that justified + keeping it; split path-specific rules into `.instructions.md` files. +- ❌ Putting tool-specific assumptions in `AGENTS.md` — keep it neutral; quirks go in that tool's file. +- ❌ Changing a command/path/convention in `AGENTS.md` without updating any kept subset in the same + PR — that is how the files go stale. diff --git a/plugins/engineering-practices/skills/conventional-release/SKILL.md b/plugins/engineering-practices/skills/conventional-release/SKILL.md index 7df5c4a..b28d09e 100644 --- a/plugins/engineering-practices/skills/conventional-release/SKILL.md +++ b/plugins/engineering-practices/skills/conventional-release/SKILL.md @@ -3,9 +3,9 @@ description: Ship changes through a squash-merge + Conventional Commits release license: Apache-2.0 metadata: github-path: conventional-release - github-ref: refs/tags/v1.4.0 + github-ref: refs/tags/v1.5.0 github-repo: https://github.com/devantler-tech/agent-skills - github-tree-sha: 511fbcd9d69f6e4bd88319533a6a95899ef25779 + github-tree-sha: 650e08053c6e52fc89fc68db9f074b122d9fbb24 name: conventional-release --- # Conventional Release @@ -54,7 +54,7 @@ So: ## Anatomy of the title -``` +```text (): ``` @@ -92,7 +92,7 @@ A breaking change is a **major** bump (`X.0.0`), signalled either way: - a `!` after the type/scope: `feat(api)!: drop the v1 endpoint`, **or** - a `BREAKING CHANGE:` footer in the body: - ``` + ```text feat(api): replace the auth header BREAKING CHANGE: clients must send `Authorization: Bearer` instead of `X-Token`. diff --git a/plugins/engineering-practices/skills/ways-of-working/SKILL.md b/plugins/engineering-practices/skills/ways-of-working/SKILL.md index 35d2972..8a3322c 100644 --- a/plugins/engineering-practices/skills/ways-of-working/SKILL.md +++ b/plugins/engineering-practices/skills/ways-of-working/SKILL.md @@ -3,9 +3,9 @@ description: 'Codifies devantler-tech engineering practices: agent-first develop license: Apache-2.0 metadata: github-path: ways-of-working - github-ref: refs/tags/v1.4.0 + github-ref: refs/tags/v1.5.0 github-repo: https://github.com/devantler-tech/agent-skills - github-tree-sha: be7d95e52d933a19e9fbdba7d4989de0af8ad8cd + github-tree-sha: 219a45e80e25b47cc23dcfed9febd526655e624c name: ways-of-working --- # Ways of Working @@ -114,7 +114,7 @@ Each repository has two core workflow files — `ci.yaml` and `cd.yaml` — plus ### Releases -Releases are automated via the [`devantler-tech/reusable-workflows/.github/workflows/create-release.yaml`](https://github.com/devantler-tech/reusable-workflows/blob/main/.github/workflows/create-release.yaml) reusable workflow. It runs [semantic-release](https://semantic-release.gitbook.io/) on `push` to `main`, calculates the next semver from [conventional commit](https://www.conventionalcommits.org/) history, and creates the tag + GitHub release — which in turn triggers the CD pipeline above. +Releases are automated via the [`devantler-tech/actions/.github/workflows/create-release.yaml`](https://github.com/devantler-tech/actions/blob/main/.github/workflows/create-release.yaml) reusable workflow. It runs [semantic-release](https://semantic-release.gitbook.io/) on `push` to `main`, calculates the next semver from [conventional commit](https://www.conventionalcommits.org/) history, and creates the tag + GitHub release — which in turn triggers the CD pipeline above. For application publishing, always use upstream releasers — e.g. [GoReleaser](https://goreleaser.com/) for Go or [dotnet-releaser](https://github.com/xoofx/dotnet-releaser) for .NET — rather than hand-rolling publish scripts.