---
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.
allowed-tools: Bash Read Edit Write
metadata:
  category: docs
  source_keys:
    - adr-0002-0003-two-tier-claude-md
  version: "0.1.0"
---

## 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.
- 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.

## Step 2 — Diff and rewrite

Read the provider file and `AGENTS.md` side by side. Separate the provider file's content into two buckets: lines that restate what `AGENTS.md` already owns (universal rules, conventions, project overview) versus lines that are genuinely provider-specific (tool syntax, IDE behavior, model-specific instructions). Rewrite 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.

## 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:

```bash
bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
```

Fix any `FAIL` and re-run until it exits `0`.

## Step 4 — Report

State which file was converted, what was removed versus kept, and the validator's final result.