feat(core): add content-guide.md to agentsmd-author
PR review feedback: Step 3 gave no concrete guidance on what good AGENTS.md content looks like, and the skill had no substantive references file (only provenance bookkeeping in sources.md), unlike sibling kyberforge skills. Adds section-by-section content guidance, the worked example, and monorepo precedence rules synthesized from the agentsmd research corpus. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
@@ -23,4 +23,5 @@ Provide the target repo root (defaults to the current directory) and, if relevan
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
|
||||
@@ -22,7 +22,7 @@ metadata:
|
||||
- agents-md-official
|
||||
- context7-websites-agents-md
|
||||
- context7-agentsmd-agents-md
|
||||
version: "0.1.0"
|
||||
version: "0.1.1"
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
@@ -45,7 +45,7 @@ Before writing anything, gather real facts: package manager and scripts (`packag
|
||||
|
||||
## Step 3 — Write or update
|
||||
|
||||
Use only sections that reflect something real about the repo. Common sections from the agents.md standard — setup/build commands, code style, testing instructions, security considerations, commit/PR conventions — are a checklist to consider, not a template to fill blindly. Prefer concrete commands and file paths over general advice.
|
||||
Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
|
||||
|
||||
## Step 4 — Check for an existing provider file
|
||||
|
||||
|
||||
118
plugins/core/skills/agentsmd-author/references/content-guide.md
Normal file
118
plugins/core/skills/agentsmd-author/references/content-guide.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
source_keys:
|
||||
- agents-md-official
|
||||
- context7-websites-agents-md
|
||||
- context7-agentsmd-agents-md
|
||||
---
|
||||
|
||||
# What good AGENTS.md content looks like
|
||||
|
||||
AGENTS.md has no required schema — there's no field to fill in, only sections that either
|
||||
earn their place or don't. Agents treat this file as a set of live directives, not
|
||||
documentation: they will actually run the commands it lists and fix failures before
|
||||
finishing a task. That means a wrong or stale line is worse than a missing one. Verify
|
||||
every command against something real in the repo before writing it down.
|
||||
|
||||
## Section-by-section guidance
|
||||
|
||||
**Setup / build commands** — the install and dev-server commands, exactly as they appear
|
||||
in `package.json` scripts, a `Makefile`, or a `Cargo.toml`/`pyproject.toml` equivalent. One
|
||||
line per command, each with a one-clause note on what it does if the name alone isn't
|
||||
obvious. Skip this section if there's genuinely nothing beyond "clone and run" — don't pad
|
||||
it with a restated `git clone`.
|
||||
|
||||
**Code style** — only conventions that aren't already enforced by a linter/formatter config
|
||||
the agent will pick up on its own (a `.eslintrc`, `rustfmt.toml`, etc. speaks for itself).
|
||||
Write down the conventions that live only in people's heads: naming patterns, module
|
||||
boundaries, patterns to avoid, anything a linter can't catch. If the repo has no
|
||||
undocumented conventions beyond what tooling enforces, skip this section.
|
||||
|
||||
**Testing instructions** — the exact command(s) to run the suite, where to find
|
||||
per-package or per-workflow test configuration (e.g. `.github/workflows/`), and any
|
||||
non-obvious requirement (a service that must be running, an env var that must be set).
|
||||
State plainly that the agent should run tests before considering a change done and fix
|
||||
failures — don't leave this implicit.
|
||||
|
||||
**Security considerations** — only repo-specific hazards: a data-handling boundary, a
|
||||
credential pattern to never hardcode, a destructive command that needs a confirmation
|
||||
step. Do not restate general security advice ("don't commit secrets") that any agent
|
||||
already assumes — that's padding, not a directive.
|
||||
|
||||
**Commit / PR conventions** — the title/format convention if one exists (e.g. a
|
||||
Conventional Commits type prefix, a ticket-number requirement), and any check that must
|
||||
pass before a PR is opened (lint, test, type-check). Point at the real command, not
|
||||
"make sure it passes."
|
||||
|
||||
**Dev environment tips** — the handful of things that save real time and are easy to miss:
|
||||
how to jump to a specific package in a monorepo without `ls`-ing around, how to register a
|
||||
new package so the toolchain sees it, where to look up a canonical name/id. This section
|
||||
is for genuine friction points observed in this repo, not generic advice.
|
||||
|
||||
## What separates useful content from padding
|
||||
|
||||
A useful section names a real file, command, or path that exists in this repo right now.
|
||||
A padded section could be pasted into any repo unchanged and still "make sense" — that's
|
||||
the tell. If a sentence would read the same in a different codebase, it doesn't belong.
|
||||
Prefer four accurate lines over twelve generic ones.
|
||||
|
||||
## Worked example (minimal project)
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## Setup commands
|
||||
- Install deps: `pnpm install`
|
||||
- Start dev server: `pnpm dev`
|
||||
- Run tests: `pnpm test`
|
||||
|
||||
## Code style
|
||||
- TypeScript strict mode
|
||||
- Single quotes, no semicolons
|
||||
- Use functional patterns where possible
|
||||
|
||||
## Dev environment tips
|
||||
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
|
||||
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
|
||||
- Check the `name` field inside each package's `package.json` to confirm the right name.
|
||||
|
||||
## Testing instructions
|
||||
- Find the CI plan in the `.github/workflows` folder.
|
||||
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
|
||||
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
|
||||
- Fix any test or type errors until the whole suite is green.
|
||||
- Add or update tests for the code you change, even if nobody asked.
|
||||
|
||||
## PR instructions
|
||||
- Title format: [<project_name>] <Title>
|
||||
- Always run `pnpm lint` and `pnpm test` before committing.
|
||||
```
|
||||
|
||||
Every line above names a real command or path — that's the standard to hold this repo's
|
||||
version to, not the specific tooling shown (a Python/Cargo/Go repo's AGENTS.md should look
|
||||
nothing like this one in its specifics, only in how concrete each line is).
|
||||
|
||||
## Monorepo / nested placement
|
||||
|
||||
```
|
||||
my-monorepo/
|
||||
├── AGENTS.md # Root-level: applies to the whole repo
|
||||
├── packages/
|
||||
│ ├── api/
|
||||
│ │ └── AGENTS.md # API-specific instructions; overrides root for this package
|
||||
│ ├── web/
|
||||
│ │ └── AGENTS.md # Web app-specific instructions
|
||||
│ └── shared/
|
||||
│ └── AGENTS.md # Shared library instructions
|
||||
```
|
||||
|
||||
Precedence rule: the file nearest the edited path wins. Nested files are **not** merged
|
||||
with the root file — an agent editing inside `packages/api/` reads only
|
||||
`packages/api/AGENTS.md`, never the root file in addition. Consequences:
|
||||
|
||||
- A nested file must stand alone. Don't write "also see the root file" — write what the
|
||||
agent needs, full stop.
|
||||
- Don't duplicate root content in a nested file "just in case." If a nested file repeats
|
||||
root-level setup instructions verbatim, that's a sign it shouldn't exist as a separate
|
||||
file at all — the subtree isn't actually different enough to warrant one.
|
||||
- Only create a nested file when the subtree has a genuinely different stack, build tool,
|
||||
or convention than the root (see `SKILL.md` Step 2 for the placement decision itself).
|
||||
@@ -5,7 +5,7 @@
|
||||
- **URL:** https://agents.md/
|
||||
- **Description:** Official agents.md website — format spec, common-sections checklist, precedence rules (nearest-file-wins, no merge across files), monorepo nesting patterns
|
||||
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Contributing files:** SKILL.md, references/content-guide.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-websites-agents-md
|
||||
@@ -13,7 +13,7 @@
|
||||
- **URL:** context7:/websites/agents_md
|
||||
- **Description:** Context7 index of the official agents.md website — overview, governance, cross-tool compatibility, configuration examples
|
||||
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Contributing files:** SKILL.md, references/content-guide.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-agentsmd-agents-md
|
||||
@@ -21,5 +21,5 @@
|
||||
- **URL:** context7:/agentsmd/agents.md
|
||||
- **Description:** Context7 index of the agentsmd/agents.md repository — format spec, nested monorepo patterns, file structure examples
|
||||
- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Contributing files:** SKILL.md, references/content-guide.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
Reference in New Issue
Block a user