# SkillPatch skill: agents-md

This skill guides an agent in creating and maintaining concise AGENTS.md and CLAUDE.md project instruction files. It provides a structured workflow for inspecting a repository, choosing the right scope, and writing minimal, actionable agent instructions. It also defines writing rules, anti-patterns, and default section templates to keep files under 60–100 lines.

You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it:

**1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs.

**2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined):

```bash
mkdir -p .claude/skills/agents-md
curl -sSL https://skillpatch.dev/install_skill/agents-md | tar -xz -C .claude/skills/
```

(`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.)


---

## Skill files (3)

- `SKILL.md`
- `SOURCES.md`
- `SPEC.md`


### `SKILL.md`

`````markdown
---
name: agents-md
description: Creates and maintains concise AGENTS.md and CLAUDE.md project instruction files. Use when asked to create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repository agent conventions, or keep coding-agent instructions minimal and reference-backed.
---

# Maintaining AGENTS.md

Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100.

## Workflow

1. Inspect before writing:
   - package manager: lock files and manifests
   - commands: `package.json`, `Makefile`, task runners, CI workflows
   - docs/specs/policies: `README.md`, `CONTRIBUTING.md`, `docs/`, `specs/`, `policies/`, `SECURITY.md`, `.github/`
   - conventions: current code patterns, test layout, generated files, legacy areas to avoid
2. Choose scope:
   - root `AGENTS.md`: repo-wide defaults
   - nested `AGENTS.md`: only when a subtree has different commands or rules
   - closest instruction file wins; keep narrower files shorter than root files
3. Write the smallest useful file.
4. Verify exact paths and commands exist.

## File Setup

- Create `AGENTS.md` at the repository root.
- If a Claude-compatible entrypoint is required, symlink `CLAUDE.md` to `AGENTS.md`.
- Do not maintain divergent `AGENTS.md` and `CLAUDE.md` copies.

## Default Sections

Use only sections that add non-obvious value.

````markdown
# Agent Instructions

## Package Manager
- Use **pnpm**: `pnpm install`

## Commands
| Task | Command |
|------|---------|
| Test file | `pnpm vitest run path/to/file.test.ts` |
| Lint file | `pnpm eslint path/to/file.ts` |

## External References
| Need | File |
|------|------|
| Setup | `CONTRIBUTING.md` |
| Architecture | `docs/architecture.md` |
| Security policy | `SECURITY.md` |

## Key Conventions
- Generated files: update with `pnpm generate`; do not edit by hand.

## Commit Attribution
AI commits MUST include:
```
Co-Authored-By: (the agent's name and attribution byline)
```
````

## Writing Rules

- Use headings, bullets, and tables; avoid paragraphs.
- Use repo-relative paths; avoid vague references like "see docs".
- Reference existing docs/specs/policies instead of copying them.
- List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.
- Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.
- Put commands in tables when there is more than one.
- Keep one rule per bullet.
- Keep rationale out unless it prevents a likely mistake.
- Do not restate linter, formatter, or typechecker config.
- Do not list installed skills or plugins.
- Do not include generic quality slogans.

## External Reference Rules

Good:

```markdown
## External References
| Need | File |
|------|------|
| API contract | `docs/api.md` |
| Release process | `docs/releasing.md` |
```

## Anti-Patterns

- welcome text, intros, conclusions, or pleasantries
- long prose explaining why instructions matter
- duplicated content from `README.md`, `CONTRIBUTING.md`, or policy docs
- project-wide commands when file-scoped commands are available
- nested `AGENTS.md` files that repeat root instructions

`````


### `SOURCES.md`

```markdown
# Sources

This file tracks material synthesized into `agents-md`.

## Selected profile

- `skills/skill-writer/references/examples/workflow-process-skill.md`

Why: this skill is a repeatable authoring workflow with pre-inspection, scoped output, validation, and failure controls.

## Current source inventory

| Source | Type | Trust tier | Retrieved | Confidence | Contribution | Usage constraints | Notes |
|---|---|---|---|---|---|---|---|
| `AGENTS.md` | repo policy | canonical | 2026-05-04 | high | Requires `skill-writer`, concise prose, exact registration expectations | local repository authority | Highest-priority local instruction source |
| `README.md` | repo policy | canonical | 2026-05-04 | high | Skill layout, `SPEC.md` convention, public inventory style | local repository authority | Confirms canonical `skills/` tree |
| `CONTRIBUTING.md` | repo policy | canonical | 2026-05-04 | high | Local testing and contribution workflow | local repository authority | Used for validation expectations |
| `skills/skill-writer/SKILL.md` and references | local canonical | canonical | 2026-05-04 | high | Skill update workflow, source capture, authoring, validation | local repository authority | Primary authoring workflow |
| `https://agents.md/` | official format guide | canonical | 2026-05-04 | high | AGENTS.md purpose, common sections, nested files, closest-file precedence | public format guidance | Supports path-backed and scoped instructions |
| `https://developers.openai.com/codex/guides/agents-md` | official product docs | canonical | 2026-05-04 | high | Codex discovery order, global/project scopes, nested precedence, size cap, verification commands | OpenAI-specific behavior | Used only for compatibility guidance |
| `https://agentskills.io/specification` | official spec | canonical | 2026-05-04 | high | Skill frontmatter, progressive disclosure, focused references | skill format guidance | Supports concise runtime file shape |

## Decisions

1. Make external file enumeration a default AGENTS.md section when docs/specs/policies exist.
   Status: adopted
   Why: AGENTS.md should point agents to exact source files instead of copying policy or asking them to scan vague directories.

2. Prefer concise root files plus nested overrides.
   Status: adopted
   Why: official AGENTS.md and Codex docs both describe hierarchical instructions where narrower files override broader guidance.

3. Keep `CLAUDE.md` as a compatibility symlink when needed.
   Status: adopted
   Why: one canonical instruction file avoids divergent provider-specific copies.

4. Treat OpenAI `AGENTS.override.md` behavior as compatibility guidance, not a shared-repo default.
   Status: adopted
   Why: it is useful for Codex-specific overrides but can surprise other tools and humans if used as the main repo contract.

5. Cut prose and examples to a compact template.
   Status: adopted
   Why: instruction-following and truncation risks grow with long agent docs; the user explicitly requested minimal prose.

## Coverage matrix

| Dimension | Coverage status | Evidence |
|---|---|---|
| Repo inspection before writing | complete | local repo policy, `skill-writer` workflow |
| External docs/specs/policies enumeration | complete | user concern, AGENTS.md format guidance |
| Nested scope and precedence | complete | official AGENTS.md guide, OpenAI Codex docs |
| Prose minimization | complete | user concern, Agent Skills progressive disclosure |
| Command precision | complete | AGENTS.md examples, repo contribution conventions |
| CLAUDE.md compatibility | complete | existing skill behavior, local repo convention |
| Provider-specific variance | partial | OpenAI Codex docs covered; other tools deferred until a concrete repo need |

## Open gaps

1. Add provider-specific discovery notes only when a concrete repository or tool requires them.
2. Add durable before/after examples only if future changes regress into long prose or vague references.

## Stopping rationale

Further retrieval is currently low-yield. The source pack covers local repo policy, the official AGENTS.md format guide, OpenAI Codex discovery behavior, and the Agent Skills specification.

## Changelog

- 2026-05-04: Added source-backed external reference guidance, nested-scope rules, `SPEC.md`, and provenance.

```


### `SPEC.md`

```markdown
# AGENTS.md Specification

## Intent

`agents-md` creates and maintains compact repository instruction files for coding agents.

It should turn scattered repo norms into a short `AGENTS.md` index: commands, non-obvious conventions, and exact links to existing docs/specs/policies.

## Scope

In scope:

- Root `AGENTS.md` files.
- Nested `AGENTS.md` files for subtree-specific overrides.
- `CLAUDE.md` compatibility symlinks when needed.
- Concise command tables, external reference tables, and commit attribution rules.
- Removing duplicated prose from existing agent docs.

Out of scope:

- Rewriting the referenced docs themselves.
- Replacing `README.md`, `CONTRIBUTING.md`, policy docs, or architecture docs.
- Listing installed skills/plugins.
- Encoding linter or formatter rules already enforced by config.
- Maintaining divergent tool-specific copies of the same instructions.

## Users And Trigger Context

- Primary users: engineers and agents maintaining repository-level agent instructions.
- Should trigger for: create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repo agent conventions, reduce agent instruction prose.
- Should not trigger for: general docs writing, PR descriptions, code review, or creating reusable agent skills.

## Runtime Contract

- Inspect repo commands, configs, docs, specs, and policies before writing.
- Prefer exact repo-relative paths and command tables.
- Enumerate external files for setup, architecture, API specs, security, release, and policy docs when present.
- Keep root guidance broad and nested guidance narrow.
- Keep `AGENTS.md` under 60 lines when practical and under 100 lines always.
- Preserve the commit attribution section when the repo requires AI co-authorship.
- Use a `CLAUDE.md` symlink only for compatibility; avoid divergent copies.

## Source And Evidence Model

Authoritative sources:

- Repository instructions, especially root `AGENTS.md`.
- `README.md`, `CONTRIBUTING.md`, package manifests, CI workflows, and settings files.
- Existing project docs, specs, security docs, and policy files.
- Official AGENTS.md format guidance and OpenAI Codex discovery behavior.

Useful improvement sources:

- Repositories with concise, path-backed agent docs.
- Review feedback about stale commands, duplicated docs, or overlong instructions.
- Agent failures caused by missing exact file paths, command ambiguity, or nested instruction conflicts.

Do not store secrets, private customer data, or long copied policy text in examples.

## Reference Architecture

- `SKILL.md` contains the runtime checklist, template, and anti-patterns.
- `SPEC.md` contains this maintenance contract.
- `SOURCES.md` stores provenance, decisions, coverage, and gaps.
- `references/`, `scripts/`, and `assets/` are unused until repeated failures require focused lookup material.

## Evaluation

- Lightweight validation: check the generated file for line count, exact commands, exact external paths, no duplicated policy prose, and no vague "see docs" references.
- Trigger QA: verify create/update/CLAUDE.md requests trigger this skill, while generic docs and skill-authoring tasks do not.
- Holdout examples: one simple single-package repo, one monorepo with nested overrides, one repo with existing docs/specs/policies to enumerate.
- Acceptance gates: the resulting `AGENTS.md` is short, command-backed, path-backed, and free of redundant style rules.

## Known Limitations

- The skill relies on local file inspection; it cannot know private policy docs that are not present or supplied.
- Some agent tools have provider-specific discovery behavior; keep compatibility notes concise and avoid making one provider the default.
- Very large monorepos may need several nested files instead of a longer root file.

## Maintenance Notes

- Update `SKILL.md` when runtime sections, templates, or anti-patterns change.
- Update `SPEC.md` when scope, evaluation, or evidence policy changes.
- Update `SOURCES.md` when AGENTS.md discovery behavior or source-backed decisions change.
- Add focused references only when repeated failures cannot be fixed with the compact runtime checklist.

```