diff --git a/plugins/core/.apm/skills/provider-adapter-author/README.md b/plugins/core/.apm/skills/provider-adapter-author/README.md index 9dc0652..1f665e0 100644 --- a/plugins/core/.apm/skills/provider-adapter-author/README.md +++ b/plugins/core/.apm/skills/provider-adapter-author/README.md @@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | +| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, and the validator flag each needs | | `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on | | `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin | | `scripts/README.md` | Directory documentation for `scripts/` | diff --git a/plugins/core/.apm/skills/provider-adapter-author/SKILL.md b/plugins/core/.apm/skills/provider-adapter-author/SKILL.md index 6629822..2de7fe5 100644 --- a/plugins/core/.apm/skills/provider-adapter-author/SKILL.md +++ b/plugins/core/.apm/skills/provider-adapter-author/SKILL.md @@ -1,36 +1,28 @@ --- name: provider-adapter-author description: > - Use when the user wants to convert a provider-specific AI instruction file - (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a - thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication - between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md" - — even if the pattern isn't named explicitly. Also invoke when - agentsmd-author detects an existing provider file overlapping with - AGENTS.md it just wrote. Detects redundant content in a provider file - relative to AGENTS.md and rewrites it down to a minimal reference (an - `@AGENTS.md`-style import where supported, or a text pointer otherwise) - plus genuinely provider-specific additions. Self-validates via a bundled - deterministic script before finishing. Do not use to write or audit - AGENTS.md itself — use agentsmd-author or agentsmd-audit. + Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions) + duplicating the repo's AGENTS.md should be cut to a thin adapter. + Not writing the AGENTS file -> `agentsmd-author`. + Not auditing the AGENTS file -> `agentsmd-audit`. allowed-tools: Bash Read Edit Write metadata: category: docs source_keys: - adr-0002-0003-two-tier-claude-md - version: "0.1.0" + version: "0.1.1" --- ## Gotchas -- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers. -- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to. -- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty. +- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers. - Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists. ## Step 1 — Detect -Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first. +Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case. + +Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to. ## Step 2 — Diff and rewrite @@ -39,6 +31,10 @@ Read the provider file and `AGENTS.md` side by side. Separate the provider file' - **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import line, keep the provider-specific bucket below it. - **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket. +The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like. + +Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty. + ## Step 3 — Self-validate Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern: @@ -47,7 +43,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] ``` -Fix any `FAIL` and re-run until it exits `0`. +Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. The size `FAIL` advises moving provider-agnostic content into `AGENTS.md`; disregard that half of its wording and delete the redundant lines instead. ## Step 4 — Report diff --git a/plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md b/plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md new file mode 100644 index 0000000..2d684cf --- /dev/null +++ b/plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md @@ -0,0 +1,23 @@ +--- +source_keys: + - adr-0002-0003-two-tier-claude-md +--- + +# Known provider instruction files + +Which files to look for when detecting a provider-specific instruction file, whether each provider +resolves a cross-file import, and what a thin adapter therefore looks like for it. + +| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag | +|---|---|---|---|---| +| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none | +| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` | +| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` | +| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` | + +A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's +own documentation before emitting an `@`-style line; an unresolved import reads as literal text and +silently drops every rule the adapter was supposed to defer to. + +Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts +independently against the same `AGENTS.md`. diff --git a/plugins/core/.apm/skills/provider-adapter-author/references/sources.md b/plugins/core/.apm/skills/provider-adapter-author/references/sources.md index 7b7071a..654c51d 100644 --- a/plugins/core/.apm/skills/provider-adapter-author/references/sources.md +++ b/plugins/core/.apm/skills/provider-adapter-author/references/sources.md @@ -5,5 +5,5 @@ - **URL:** (in-repo precedent — not an external source or plugin research corpus entry) - **Description:** This repo's own two-tier CLAUDE.md/AGENTS.md pattern: AGENTS.md is the provider-agnostic source of always-on rules; provider-specific files (CLAUDE.md) become thin adapters that import it (`@AGENTS.md` plus provider-specific additions). Grounds this skill's entire adapter-conversion design — the "thin adapter" shape, the `@`-import convention, and the size/duplication expectations enforced by `scripts/validate-adapter.sh`. - **Research doc:** docs/adr/0002-two-tier-claude-md.md, docs/adr/0003-agents-md-provider-agnostic-entry-point.md, providers/claude-code/CLAUDE.md (in-repo ADRs and a live example, not a plugin research corpus entry; referenced here since this skill's design is modeled directly on an existing implementation rather than external research) -- **Contributing files:** SKILL.md +- **Contributing files:** SKILL.md, references/provider-matrix.md - **Status:** `extracted` diff --git a/plugins/core/skills/provider-adapter-author/README.md b/plugins/core/skills/provider-adapter-author/README.md index 9dc0652..1f665e0 100644 --- a/plugins/core/skills/provider-adapter-author/README.md +++ b/plugins/core/skills/provider-adapter-author/README.md @@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | +| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, and the validator flag each needs | | `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on | | `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin | | `scripts/README.md` | Directory documentation for `scripts/` | diff --git a/plugins/core/skills/provider-adapter-author/SKILL.md b/plugins/core/skills/provider-adapter-author/SKILL.md index 6629822..2de7fe5 100644 --- a/plugins/core/skills/provider-adapter-author/SKILL.md +++ b/plugins/core/skills/provider-adapter-author/SKILL.md @@ -1,36 +1,28 @@ --- name: provider-adapter-author description: > - Use when the user wants to convert a provider-specific AI instruction file - (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a - thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication - between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md" - — even if the pattern isn't named explicitly. Also invoke when - agentsmd-author detects an existing provider file overlapping with - AGENTS.md it just wrote. Detects redundant content in a provider file - relative to AGENTS.md and rewrites it down to a minimal reference (an - `@AGENTS.md`-style import where supported, or a text pointer otherwise) - plus genuinely provider-specific additions. Self-validates via a bundled - deterministic script before finishing. Do not use to write or audit - AGENTS.md itself — use agentsmd-author or agentsmd-audit. + Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions) + duplicating the repo's AGENTS.md should be cut to a thin adapter. + Not writing the AGENTS file -> `agentsmd-author`. + Not auditing the AGENTS file -> `agentsmd-audit`. allowed-tools: Bash Read Edit Write metadata: category: docs source_keys: - adr-0002-0003-two-tier-claude-md - version: "0.1.0" + version: "0.1.1" --- ## Gotchas -- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers. -- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to. -- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty. +- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers. - Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists. ## Step 1 — Detect -Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first. +Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case. + +Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to. ## Step 2 — Diff and rewrite @@ -39,6 +31,10 @@ Read the provider file and `AGENTS.md` side by side. Separate the provider file' - **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import line, keep the provider-specific bucket below it. - **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket. +The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like. + +Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty. + ## Step 3 — Self-validate Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern: @@ -47,7 +43,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] ``` -Fix any `FAIL` and re-run until it exits `0`. +Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. The size `FAIL` advises moving provider-agnostic content into `AGENTS.md`; disregard that half of its wording and delete the redundant lines instead. ## Step 4 — Report diff --git a/plugins/core/skills/provider-adapter-author/references/provider-matrix.md b/plugins/core/skills/provider-adapter-author/references/provider-matrix.md new file mode 100644 index 0000000..2d684cf --- /dev/null +++ b/plugins/core/skills/provider-adapter-author/references/provider-matrix.md @@ -0,0 +1,23 @@ +--- +source_keys: + - adr-0002-0003-two-tier-claude-md +--- + +# Known provider instruction files + +Which files to look for when detecting a provider-specific instruction file, whether each provider +resolves a cross-file import, and what a thin adapter therefore looks like for it. + +| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag | +|---|---|---|---|---| +| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none | +| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` | +| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` | +| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` | + +A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's +own documentation before emitting an `@`-style line; an unresolved import reads as literal text and +silently drops every rule the adapter was supposed to defer to. + +Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts +independently against the same `AGENTS.md`. diff --git a/plugins/core/skills/provider-adapter-author/references/sources.md b/plugins/core/skills/provider-adapter-author/references/sources.md index 7b7071a..654c51d 100644 --- a/plugins/core/skills/provider-adapter-author/references/sources.md +++ b/plugins/core/skills/provider-adapter-author/references/sources.md @@ -5,5 +5,5 @@ - **URL:** (in-repo precedent — not an external source or plugin research corpus entry) - **Description:** This repo's own two-tier CLAUDE.md/AGENTS.md pattern: AGENTS.md is the provider-agnostic source of always-on rules; provider-specific files (CLAUDE.md) become thin adapters that import it (`@AGENTS.md` plus provider-specific additions). Grounds this skill's entire adapter-conversion design — the "thin adapter" shape, the `@`-import convention, and the size/duplication expectations enforced by `scripts/validate-adapter.sh`. - **Research doc:** docs/adr/0002-two-tier-claude-md.md, docs/adr/0003-agents-md-provider-agnostic-entry-point.md, providers/claude-code/CLAUDE.md (in-repo ADRs and a live example, not a plugin research corpus entry; referenced here since this skill's design is modeled directly on an existing implementation rather than external research) -- **Contributing files:** SKILL.md +- **Contributing files:** SKILL.md, references/provider-matrix.md - **Status:** `extracted`