[PR #34] [MERGED] docs: add AGENTS.md agent guide and CLAUDE.md shim #32

New issue

Closed

opened 2026-10-26 22:34:12 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:34:12 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-skills/pull/34
Author: @mattmillerai
Created: 9/16/2026
Status: ✅ Merged
Merged: 10/22/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-3576-bootstrap-agents-md

📝 Commits (1)

c50dc1d docs: add AGENTS.md agent guide and CLAUDE.md shim

📊 Changes

2 files changed (+78 additions, -0 deletions)

View changed files

➕ AGENTS.md (+76 -0)
➕ CLAUDE.md (+2 -0)

📄 Description

ELI-5

This repo had no top-level instructions telling an AI coding agent how to work in
it. This PR adds two small files: AGENTS.md (the cross-agent standard — what the
repo is, how to check your work, where things live, and the house rules) and
CLAUDE.md (a one-line shim that just pulls AGENTS.md in, because Claude Code
reads CLAUDE.md and doesn't fall back to AGENTS.md). No code changes.

What & why

Bootstrap agent instructions per the org "Pillar 1: Agentic Engineering" standard:
a single source of truth in AGENTS.md plus a Claude Code shim.

AGENTS.md (76 lines, well under the 200-line cap) — authored from the
repo's actual contents (README, manifests, CI, top-level layout). Covers:
one-paragraph purpose; the one real check the project runs
(claude plugin validate ./claude-code — verified locally, exit 0); a directory
map; the authoring conventions/gotchas visible in the repo (the README
"steer the approach, defer the specifics" rule, Conventional Commits style,
claude-code/ canonical vs frozen skills/, comfy-cli skills living elsewhere,
public-repo hygiene); a CI note; and links to deeper docs.
CLAUDE.md — exactly the canonical shim (@AGENTS.md import), byte-for-byte.

Verification

AGENTS.md is 76 lines (< 200). ✓
CLAUDE.md matches the canonical shim exactly (verified via cat -A). ✓
No .cursorrules present anywhere (legacy; not added). ✓
claude plugin validate ./claude-code → Validation passed (exit 0) before and
after the change — the only command listed in AGENTS.md, and it works. ✓
CI: the sole workflow (detect-unreviewed-merge.yml) runs on push to main as a
SOC 2 compliance check, not a build/test/lint gate; there is no test/lint
workflow to break. This PR adds only Markdown, so no CI content gate is affected.

Residual

Nested AGENTS.md files not added. The org standard notes that nested
directories (claude-code/, skills/, openclaw/) may each grow their own
AGENTS.md + CLAUDE.md shim. This PR intentionally ships only the root pair —
the ticket scopes the work to a root file and says a tight file beats a
speculative one. If subsystem detail later warrants per-directory guides, that is
a follow-up.
Parent epic not read. The parent epic (the "bootstrap AGENTS.md in active
repos" tracker) was named to me but its body/comments were not fetched and are
not reachable from this sandbox — an unexercised artifact. Nothing in it is
expected to change this repo's root bootstrap, which follows the stated canonical
standard, but it was not exercised.

Provenance

Authored by: agent-work loop
Verified: claude plugin validate ./claude-code passes; AGENTS.md 76 lines
(< 200); CLAUDE.md byte-exact canonical shim; no .cursorrules.
Deviations: none.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-skills/pull/34 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 9/16/2026 **Status:** ✅ Merged **Merged:** 10/22/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-3576-bootstrap-agents-md` --- ### 📝 Commits (1) - [`c50dc1d`](https://github.com/Comfy-Org/comfy-skills/commit/c50dc1de7c1167d1294cc1dc5f8a80668a896bd9) docs: add AGENTS.md agent guide and CLAUDE.md shim ### 📊 Changes **2 files changed** (+78 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `AGENTS.md` (+76 -0) ➕ `CLAUDE.md` (+2 -0) </details> ### 📄 Description ## ELI-5 This repo had no top-level instructions telling an AI coding agent how to work in it. This PR adds two small files: `AGENTS.md` (the cross-agent standard — what the repo is, how to check your work, where things live, and the house rules) and `CLAUDE.md` (a one-line shim that just pulls `AGENTS.md` in, because Claude Code reads `CLAUDE.md` and doesn't fall back to `AGENTS.md`). No code changes. ## What & why Bootstrap agent instructions per the org "Pillar 1: Agentic Engineering" standard: a single source of truth in `AGENTS.md` plus a Claude Code shim. - **`AGENTS.md`** (76 lines, well under the 200-line cap) — authored from the repo's actual contents (README, manifests, CI, top-level layout). Covers: one-paragraph purpose; the one real check the project runs (`claude plugin validate ./claude-code` — verified locally, exit 0); a directory map; the authoring conventions/gotchas visible in the repo (the README "steer the approach, defer the specifics" rule, Conventional Commits style, `claude-code/` canonical vs frozen `skills/`, comfy-cli skills living elsewhere, public-repo hygiene); a CI note; and links to deeper docs. - **`CLAUDE.md`** — exactly the canonical shim (`@AGENTS.md` import), byte-for-byte. ## Verification - `AGENTS.md` is 76 lines (< 200). ✓ - `CLAUDE.md` matches the canonical shim exactly (verified via `cat -A`). ✓ - No `.cursorrules` present anywhere (legacy; not added). ✓ - `claude plugin validate ./claude-code` → `Validation passed` (exit 0) before and after the change — the only command listed in `AGENTS.md`, and it works. ✓ - CI: the sole workflow (`detect-unreviewed-merge.yml`) runs on push to `main` as a SOC 2 compliance check, not a build/test/lint gate; there is no test/lint workflow to break. This PR adds only Markdown, so no CI content gate is affected. ## Residual - **Nested `AGENTS.md` files not added.** The org standard notes that nested directories (`claude-code/`, `skills/`, `openclaw/`) may each grow their own `AGENTS.md` + `CLAUDE.md` shim. This PR intentionally ships only the root pair — the ticket scopes the work to a root file and says a tight file beats a speculative one. If subsystem detail later warrants per-directory guides, that is a follow-up. - **Parent epic not read.** The parent epic (the "bootstrap AGENTS.md in active repos" tracker) was named to me but its body/comments were not fetched and are not reachable from this sandbox — an unexercised artifact. Nothing in it is expected to change this repo's root bootstrap, which follows the stated canonical standard, but it was not exercised. ## Provenance - **Authored by:** agent-work loop - **Verified:** `claude plugin validate ./claude-code` passes; `AGENTS.md` 76 lines (< 200); `CLAUDE.md` byte-exact canonical shim; no `.cursorrules`. - **Deviations:** none. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:34:12 +00:00