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.