feat(core): add agentsmd-author skill
Creates/updates a target repo's AGENTS.md by exploring real repo conventions, supports nested monorepo placement, closes out via agentsmd-audit, and composes into provider-adapter-author for provider-file reconciliation. Completes the three-skill trio from ADR-0012.
This commit is contained in:
26
plugins/core/skills/agentsmd-author/README.md
Normal file
26
plugins/core/skills/agentsmd-author/README.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# agentsmd-author
|
||||
|
||||
Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
|
||||
|
||||
## What it does
|
||||
|
||||
Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
|
||||
|
||||
## Before you start
|
||||
|
||||
The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agentsmd-author
|
||||
```
|
||||
|
||||
Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
56
plugins/core/skills/agentsmd-author/SKILL.md
Normal file
56
plugins/core/skills/agentsmd-author/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: agentsmd-author
|
||||
description: >
|
||||
Use when the user wants to create or update a repo's AGENTS.md file
|
||||
("write an AGENTS.md for this repo", "add setup/test instructions for
|
||||
agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
|
||||
if they don't name the file explicitly, e.g. "document this for AI coding
|
||||
tools" or "make sure agents know how to run tests here". Writes/updates
|
||||
AGENTS.md by exploring the target repo for real build, test, lint, and
|
||||
style conventions — never invents commands. Supports nested monorepo
|
||||
placement (a subdirectory can get its own AGENTS.md following
|
||||
nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
|
||||
inline, and calls provider-adapter-author when an existing provider file
|
||||
(CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
|
||||
an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
|
||||
not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
|
||||
provider-adapter-author instead.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
category: docs
|
||||
source_keys:
|
||||
- agents-md-official
|
||||
- context7-websites-agents-md
|
||||
- context7-agentsmd-agents-md
|
||||
version: "0.1.0"
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
|
||||
- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
|
||||
- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
|
||||
- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
|
||||
- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
|
||||
|
||||
## Step 1 — Explore the target repo
|
||||
|
||||
Before writing anything, gather real facts: package manager and scripts (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.), a `Makefile` or task runner, CI config (`.github/workflows/`, etc.) for the commands it actually runs, linter/formatter config files, and any existing docs (`README.md`, existing `AGENTS.md`) describing conventions. Note whether any subdirectory looks like its own package with a different stack.
|
||||
|
||||
## Step 2 — Decide placement
|
||||
|
||||
- No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions.
|
||||
- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
|
||||
- Otherwise → update the existing file(s) in place.
|
||||
|
||||
## 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.
|
||||
|
||||
## Step 4 — Check for an existing provider file
|
||||
|
||||
Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the `provider-adapter-author` skill on it to reconcile — don't rewrite it yourself.
|
||||
|
||||
## Step 5 — Audit and report
|
||||
|
||||
Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.
|
||||
25
plugins/core/skills/agentsmd-author/references/sources.md
Normal file
25
plugins/core/skills/agentsmd-author/references/sources.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Sources
|
||||
|
||||
## agents-md-official
|
||||
|
||||
- **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
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-websites-agents-md
|
||||
|
||||
- **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
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-agentsmd-agents-md
|
||||
|
||||
- **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
|
||||
- **Status:** `extracted`
|
||||
Reference in New Issue
Block a user