writing-agents-md
Writing Agents MD
Overview
AGENTS.md and CLAUDE.md should be minimal guardrails, not repo handbooks.
Do not assume more global instructions improve outcomes; extra always-on guidance often slows or misdirects work.
Keep only information that is all three:
- hard to discover from the repo itself
- globally relevant across most tasks
- stable enough not to rot quickly
If a detail fails any of those tests, delete it, narrow it, or move it into a skill.
When to Use
- Creating a new
AGENTS.mdorCLAUDE.md
More from shihyuho/skills
lessons-learned
Use when starting, executing, or finishing non-trivial implementation tasks where reusable constraints may matter. Recall relevant lessons before work, capture reusable corrections or discoveries during and after work, and keep project memory in `docs/lessons/`.
105fanfuaji
Use when user requests Chinese terminology conversion, checking, or ensuring terminology - "使用繁體中文", "使用台灣用語", "轉換成台灣用語", "確保都是台灣用語", "統一台灣用語", "改成台灣用語", "用台灣的說法", "簡體轉繁體", "繁體轉簡體", "全部改成繁體", "轉成台灣繁體", check/ensure Taiwan/Hong Kong/China terminology, simplified/traditional conversion, or phonetic transcription (Pinyin/Bopomofo)
60executing-plans-preflight
Use before any implementation start — auto-detects and fixes git state issues (branch, dirty files, remote sync) with one confirmation per fix. Trigger on "start implementation", "implement this plan", "start coding", "execute plan", "開始實作", "執行計劃", or any signal that coding is about to begin.
42agent-install-guide
Use when creating INSTALL.md, setup guides, or configuration instructions intended to be executed by AI agents.
35harvest
Capture project memory from planning-with-files source-of-truth into Obsidian-compatible second-brain notes in docs/notes. Use for milestone summaries, decision capture, and timeline snapshots. Trigger on: harvest, /harvest, harvest this, save this to second brain, save what we just did, document this work, capture this knowledge.
29skill-design
Design and refactor Agent Skills with concise, high-signal instructions and explicit trigger metadata. Use when creating a new skill, revising SKILL.md/README.md structure, or improving skill discoverability and portability.
27