ee3f9a081ba372bbca75f87d2fe9952c0f26f509

Message

Update AGENTS.md cleanup skill

Diff

This diff is truncated to protect this page.

 1diff --git a/dot_agents/skills/agents-md-cleanup/SKILL.md b/dot_agents/skills/agents-md-cleanup/SKILL.md
 2index e98915be7a43cffdf6bbeae9f0fd4ec731268b30..2fb6393d884e3cedf1417d44c0eccd3b10473e41 100644
 3--- a/dot_agents/skills/agents-md-cleanup/SKILL.md
 4+++ b/dot_agents/skills/agents-md-cleanup/SKILL.md
 5@@ -1,21 +1,64 @@
 6 ---
 7 name: agents-md-cleanup
 8-description: Cleans and right-sizes repository AGENTS.md files. Use when an agent guide is too long, repetitive, overly detailed, or needs a concise repository map and development guidance.
 9-disable-model-invocation: true
10+description: Cleans and right-sizes repository AGENTS.md files while preserving generated-content contracts and human-owned guidance. Use when an agent guide is too long, repetitive, or overly detailed.
11 ---
12 
13 # AGENTS.md cleanup
14 
15 Use this skill to make AGENTS.md a navigation and working guide, not a reference manual.
16 
17-## Workflow
18+## Respect the maintenance contract
19 
20-1. Find every `AGENTS.md` inside the target repository. Do not search parent directories or the whole home directory.
21-2. Read each file completely. Read its repository README and local instructions when you need to verify setup, test, release, or safety guidance.
22-3. Check `git status --short` before editing. Preserve user changes.
23-4. Check whether an AGENTS.md has generated-content markers or an auto-maintenance workflow. Preserve both unless the user asks to remove the automation.
24-5. Rewrite only the relevant AGENTS.md files. Use a target of 100–200 lines unless the user gives a different target.
25-6. Run `git diff --check`, verify the line count, and review the diff for lost safety constraints.
26+Many repositories use `agents-md.yml` to update these guides. Its ownership rules override normal cleanup preferences:
27+
28+- Content outside `AGENTS-MD:AUTO` markers is human-owned. Preserve it verbatim.
29+- Content inside the markers is machine-owned and may be reconciled with the code.
30+- `AGENTS-MD:PIN` blocks inside the auto region are human-frozen. Preserve their markers and text byte-for-byte. Do not add pins yourself.
31+- If a pinned claim conflicts with the code, leave the pin unchanged and add a short nearby unpinned note for a human.
32+- Do not make a stamp-only change to `_Last synced by agents-md.yml`. Update it only when the same file has other content changes.
33+
34+## Determine scope
35+
36+1. Find tracked `AGENTS.md` files inside the target repository. Do not search parent directories or the whole home directory.
37+2. Each guide owns its own directory. A nested guide covers its directory instead of its ancestor guide.
38+3. If the task targets all guides, read every guide and explore only its owned scope. In a nested guide, use paths relative to that directory.
39+4. Read the current guide, then verify its claims from code, configuration, scripts, and package tests. Never speculate.
40+5. Check `git status --short` before editing. Preserve user changes.
41+6. Modify only the requested AGENTS.md files.
42+
43+## Adopt or update a guide
44+
45+### Existing auto-managed guide
46+
47+Keep its notice, markers, human-owned text, and pins. Edit only the content between these markers:
48+
49+```markdown
50+<!-- AGENTS-MD:AUTO:START -->
51+<!-- AGENTS-MD:AUTO:END -->
52+```
53+
54+The auto region uses this section order. Omit a section only when it does not apply:
55+
56+1. `## Overview`
57+2. `## Tech Stack`
58+3. `## Repository Map`
59+4. `## Setup`
60+5. `## Build, Test & Run`
61+6. `## Conventions`
62+7. `## Testing`
63+8. `## Gotchas & Constraints`
64+9. `## Key Entry Points`
65+10. the `Last synced` line
66+
67+Keep required sections concise. For example, list languages and package managers in Tech Stack, but do not add a dependency inventory.
68+
69+### Existing human-only guide
70+