holocron/plugins/core/skills/provider-adapter-author/SKILL.md at a8cd5e881df81d0a7b514b5d466ccdc93e783093

Files

Defame1297 a8cd5e881d fix(core): strip a BOM before the adapter import check, and split usage exits

Narrowing has_reference to bool(import_lines) meant a UTF-8 BOM hid the import
line, since the BOM is not \s: a CLAUDE.md whose first line is @AGENTS.md failed
with 'no reference to AGENTS.md' and was told to add the line already in front of
it. Decoding is now strict too, so a non-UTF-8 adapter gets an encoding
diagnostic instead of being mangled and then graded on the mangling.

Usage errors move to exit 2. They shared exit 1 with real findings, while the
skill tells the agent to fix any non-zero exit by editing the provider file.

The whole-line import rule is kept deliberately -- accepting an inline @AGENTS.md
would also accept one inside backticks, which is the silent-drop failure the
validator exists to catch -- and the message now says so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti

2026-08-31 19:46:07 +00:00

3.3 KiB

Raw Blame History

name, description, allowed-tools, metadata

name

description

allowed-tools

metadata

provider-adapter-author

Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions) duplicating the repo's AGENTS.md should be cut to a thin adapter — "make CLAUDE.md just import AGENTS.md". Not writing the AGENTS file -> `agentsmd-author`. Not auditing the AGENTS file -> `agentsmd-audit`.

Bash Read Edit Write

Gotchas

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; do not assume a caller skill exists. Detect the provider file, confirm AGENTS.md, and run the closeout validator yourself in both cases (references/provider-matrix.md).

Step 1 — Detect

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

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 on a line of its own, keep the provider-specific bucket below it. An import folded into a sentence is not the thin-adapter shape and scripts/validate-adapter.sh will not credit 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:

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

Fix any FAIL by editing the provider file, and re-run until it exits 0. Exit 2 is not a FAIL: it means the invocation or the input is wrong — a bad or missing argument, or a file that is not UTF-8 — so fix that, not the adapter.

Step 4 — Report

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

3.3 KiB Raw Blame History