{"id":"c046237c-89bc-44d4-9a11-ccc771d2767b","shortId":"EHFzcY","kind":"skill","title":"writing-agents-md","tagline":"Use when the user asks to create, review, audit, migrate, or update an AGENTS.md file for a repository, package, subproject, or monorepo. This skill writes agent-facing repository guidance grounded in project evidence, including setup, build/test commands, code style, testing, se","description":"# Writing AGENTS.md\n\nCreate, review, or revise `AGENTS.md`: a standard Markdown \"README for agents\" that gives coding agents the project-specific context they need without cluttering the human README.\n\n## Grounding workflow\n\nBefore writing, inspect the repository instead of guessing:\n\n- Read existing guidance: `README.md`, `CONTRIBUTING.md`, current `AGENTS.md`, package-level docs, `.github/workflows/*`, config files, and obvious build manifests (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `justfile`, `Makefile`, etc.).\n- Check the tree for monorepos, generated directories, vendored code, large data, or subprojects that may need scoped instructions.\n- Verify commands from scripts, task files, Make/Just recipes, or CI definitions. Do not invent commands from ecosystem habits.\n- If sources conflict, prefer executable config and CI over prose; preserve uncertainty as a short note or ask one focused question rather than silently choosing.\n- If updating an existing `AGENTS.md`, preserve correct project-specific rules and remove stale or unverifiable claims.\n- Prefer repository evidence over generic best practices. Label uncertainty briefly or omit it rather than inventing commands.\n\n## Review mode\n\nWhen asked to review an existing `AGENTS.md` instead of drafting one:\n\n- Check it against repository evidence and the principles below.\n- Report concrete findings with severity, affected section/path, evidence, and a suggested replacement.\n- Prioritize incorrect commands, stale paths, missing scoped guidance, unsafe instructions, and conflicts with closer `AGENTS.md` files or explicit user directions.\n- Use this concise review shape when not directly editing: `Findings`, `Suggested edits`, `Verified evidence`, `Open questions`.\n- If edits are requested or clearly beneficial, make a bounded revision and then verify that all listed commands/paths remain grounded.\n\n## AGENTS.md principles\n\n- `AGENTS.md` is plain Markdown; do not add YAML frontmatter or required-field scaffolding to the generated file.\n- Default to a root-level `AGENTS.md`; add package-level files only when scoped instructions differ or the user asks for a specific subproject.\n- Keep it agent-focused: include details a coding agent needs to work safely and verify changes, not product marketing or broad README content.\n- Treat it as living documentation. Make rules actionable, testable, and easy to update.\n- User prompts override repository instructions. When multiple `AGENTS.md` files apply, the closest file to the edited path takes precedence.\n- For large monorepos, prefer nested `AGENTS.md` files in packages/subprojects instead of one overloaded root file. Root files should describe global rules and point to scoped files.\n- Avoid copying broad human-facing README content, long install walkthroughs, unverifiable \"best practices\", personal preferences, or rules that merely restate tool defaults.\n\n## File requirements\n\n- Name the file exactly `AGENTS.md`; when the user specifies a package or subdirectory, place it in that scope.\n- Use a clear title; `# Repository Guidelines` is a good default unless the repo already uses another title.\n- Keep it concise: usually 200–500 words for a root file. Go longer only when the repository genuinely needs more operational detail.\n- Use direct imperative bullets with concrete examples: commands, paths, naming patterns, and verification gates.\n- Do not duplicate README installation walkthroughs unless agents specifically need those commands to run checks.\n- Do not include secrets, credentials, private URLs, speculative claims, or instructions that encourage bypassing security checks.\n- For review responses, prefer findings first; for file creation/update responses, summarize changed paths and verification.\n\n## Recommended content\n\nChoose sections that match the repository; omit empty or irrelevant sections. The core coverage from agents.md is: project overview, build and test commands, code style guidelines, testing instructions, security considerations, and extra teammate-like instructions such as commit/PR rules, deployment gotchas, large datasets, or migration steps.\n\n### Project structure and scope\n\n- Summarize key directories and what agents should edit or avoid.\n- Mention generated/vendor/build artifacts that should not be hand-edited.\n- In monorepos, state how to locate the relevant package and whether package-level `AGENTS.md` files override root guidance.\n- Example split: root `AGENTS.md` owns repo-wide safety rules and CI gates; `packages/api/AGENTS.md` owns API migrations and schema tests; `packages/web/AGENTS.md` owns UI screenshots and browser checks.\n\n### Build, test, and development commands\n\n- List the smallest reliable commands for setup, local development, formatting, linting, typechecking, tests, and full CI-equivalent verification.\n- Include targeted variants when useful, e.g. package filters or single-test patterns.\n- State required working directory if commands must run from repo root or a package directory.\n- Prefer commands proven by `package.json` scripts, `just --list`, `make help`, lockfiles, or CI jobs; if a command cannot be confirmed, leave it out or mark it as an example.\n\n### Code style and conventions\n\n- Capture formatting tools, language versions, strictness settings, naming patterns, architectural boundaries, and dependency rules.\n- Prefer enforceable rules over taste statements.\n\n### Testing and verification\n\n- Explain where tests live, naming conventions, fixture practices, coverage expectations, and which checks agents should run after specific change types.\n- Include relevant programmatic checks because agents may attempt listed commands and fix failures before finishing.\n- Encourage adding or updating tests with behavior changes when that is true for the repo.\n\n### Security, configuration, and data\n\n- Call out secret handling, environment files, migrations, external services, large datasets, deployment steps, and destructive commands.\n- Tell agents how to use safe examples (`.env.example`, local mocks, dry-run flags) when available.\n\n### Commit and PR guidance\n\n- Derive commit style from recent history if requested or relevant.\n- Include PR expectations such as linked issues, screenshots for UI changes, migration notes, and verification summaries.\n\n## Migration and compatibility notes\n\n- If the repo has older agent instruction files, migrate by renaming to `AGENTS.md`; optionally leave a symlink for tools that still expect the old name, e.g. `mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md`.\n- For tools that need explicit configuration, add minimal setup notes only when the repo uses them (for example Aider `read: AGENTS.md` or Gemini CLI `context.fileName`).\n\n## Final checks\n\nBefore finishing:\n\n- Verify every listed command/path exists or is clearly marked as an example.\n- Ensure rules do not conflict with nearer scoped instructions or explicit user requirements.\n- Check that review output uses the requested findings format when applicable.\n- Keep one clear purpose per section; remove filler and generic advice.\n- If you edited the file, summarize affected path(s), evidence used, and verification performed.","tags":["writing","agents","skills","narumiruna","agent-skills"],"capabilities":["skill","source-narumiruna","skill-writing-agents-md","topic-agent-skills"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/narumiruna/skills/writing-agents-md","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add narumiruna/skills","source_repo":"https://github.com/narumiruna/skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (7,184 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:47.856Z","embedding":null,"createdAt":"2026-05-18T19:13:47.856Z","updatedAt":"2026-05-18T19:13:47.856Z","lastSeenAt":"2026-05-18T19:13:47.856Z","tsv":"'200':487 '500':488 'action':372 'ad':828 'add':304,323,951 'advic':1020 'affect':233,1027 'agent':3,31,59,63,344,350,526,623,805,817,863,917 'agent-fac':30 'agent-focus':343 'agent.md':939,944 'agents.md':18,48,53,92,176,214,254,296,298,322,385,402,452,582,652,660,924,940,943,965 'aider':963 'alreadi':479 'anoth':481 'api':672 'appli':387 'applic':1009 'architectur':778 'artifact':630 'ask':9,164,209,336 'attempt':819 'audit':13 'avail':877 'avoid':423,627 'behavior':833 'benefici':282 'best':194,435 'bound':285 'boundari':779 'briefli':198 'broad':362,425 'browser':682 'build':102,586,684 'build/test':41 'bullet':508 'bypass':547 'call':846 'cannot':753 'captur':769 'cargo.toml':106 'chang':357,561,810,834,902 'check':111,219,533,549,683,804,815,971,999 'choos':171,567 'ci':138,154,668,705,748 'ci-equival':704 'claim':188,542 'clear':281,468,981,1012 'cli':968 'closer':253 'closest':389 'clutter':72 'code':43,62,119,349,590,765 'command':42,130,143,205,242,512,530,589,688,693,726,737,752,821,861 'command/path':977 'commands/paths':293 'commit':878,883 'commit/pr':605 'compat':910 'concis':262,485 'concret':229,510 'config':98,152 'configur':843,950 'confirm':755 'conflict':149,251,990 'consider':596 'content':364,430,566 'context':68 'context.filename':969 'contributing.md':90 'convent':768,797 'copi':424 'core':579 'correct':178 'coverag':580,800 'creat':11,49 'creation/update':558 'credenti':538 'current':91 'data':121,845 'dataset':610,856 'default':316,445,475 'definit':139 'depend':781 'deploy':607,857 'deriv':882 'describ':415 'destruct':860 'detail':347,504 'develop':687,697 'differ':332 'direct':259,267,506 'directori':117,620,724,735 'doc':96 'document':369 'draft':217 'dri':873 'dry-run':872 'duplic':521 'e.g':713,937 'easi':375 'ecosystem':145 'edit':268,271,277,393,625,637,1023 'empti':574 'encourag':546,827 'enforc':784 'ensur':986 'env.example':869 'environ':850 'equival':706 'etc':110 'everi':975 'evid':38,191,223,235,273,1030 'exact':451 'exampl':511,657,764,868,962,985 'execut':151 'exist':87,175,213,978 'expect':801,894,933 'explain':792 'explicit':257,949,996 'extern':853 'extra':598 'face':32,428 'failur':824 'field':310 'file':19,99,134,255,315,327,386,390,403,411,413,422,446,450,493,557,653,851,919,1025 'filler':1017 'filter':715 'final':970 'find':230,269,554,1006 'finish':826,973 'first':555 'fix':823 'fixtur':798 'flag':875 'focus':166,345 'format':698,770,1007 'frontmatt':306 'full':703 'gate':518,669 'gemini':967 'generat':116,314 'generated/vendor/build':629 'generic':193,1019 'genuin':500 'github/workflows':97 'give':61 'global':416 'go':494 'go.mod':107 'good':474 'gotcha':608 'ground':35,76,295 'guess':85 'guidanc':34,88,247,656,881 'guidelin':471,592 'habit':146 'hand':636 'hand-edit':635 'handl':849 'help':745 'histori':887 'human':74,427 'human-fac':426 'imper':507 'includ':39,346,536,708,812,892 'incorrect':241 'inspect':80 'instal':432,523 'instead':83,215,406 'instruct':128,249,331,382,544,594,602,918,994 'invent':142,204 'irrelev':576 'issu':898 'job':749 'justfil':108 'keep':341,483,1010 'key':619 'label':196 'languag':772 'larg':120,398,609,855 'leav':756,926 'level':95,321,326,651 'like':601 'link':897 'lint':699 'list':292,689,743,820,976 'live':368,795 'ln':941 'local':696,870 'locat':643 'lockfil':746 'long':431 'longer':495 'make':283,370,744 'make/just':135 'makefil':109 'manifest':103 'mark':760,982 'markdown':56,301 'market':360 'match':570 'may':125,818 'md':4 'mention':628 'mere':442 'migrat':14,612,673,852,903,908,920 'minim':952 'miss':245 'mock':871 'mode':207 'monorepo':26,115,399,639 'multipl':384 'must':727 'mv':938 'name':448,514,776,796,936 'nearer':992 'need':70,126,351,501,528,948 'nest':401 'note':162,904,911,954 'obvious':101 'old':935 'older':916 'omit':200,573 'one':165,218,408,1011 'open':274 'oper':503 'option':925 'output':1002 'overload':409 'overrid':380,654 'overview':585 'own':661,671,678 'packag':23,94,325,458,646,650,714,734 'package-level':93,324,649 'package.json':104,740 'packages/api/agents.md':670 'packages/subprojects':405 'packages/web/agents.md':677 'path':244,394,513,562,1028 'pattern':515,720,777 'per':1014 'perform':1034 'person':437 'place':461 'plain':300 'point':419 'pr':880,893 'practic':195,436,799 'preced':396 'prefer':150,189,400,438,553,736,783 'preserv':157,177 'principl':226,297 'priorit':240 'privat':539 'product':359 'programmat':814 'project':37,66,180,584,614 'project-specif':65,179 'prompt':379 'prose':156 'proven':738 'purpos':1013 'pyproject.toml':105 'question':167,275 'rather':168,202 'read':86,964 'readm':57,75,363,429,522 'readme.md':89 'recent':886 'recip':136 'recommend':565 'relev':645,813,891 'reliabl':692 'remain':294 'remov':184,1016 'renam':922 'replac':239 'repo':478,663,730,841,914,958 'repo-wid':662 'report':228 'repositori':22,33,82,190,222,381,470,499,572 'request':279,889,1005 'requir':309,447,722,998 'required-field':308 'respons':552,559 'restat':443 'review':12,50,206,211,263,551,1001 'revis':52,286 'root':320,410,412,492,655,659,731 'root-level':319 'rule':182,371,417,440,606,666,782,785,987 'run':532,728,807,874 'safe':354,867 'safeti':665 'scaffold':311 'schema':675 'scope':127,246,330,421,465,617,993 'screenshot':680,899 'script':132,741 'se':46 'secret':537,848 'section':568,577,1015 'section/path':234 'secur':548,595,842 'servic':854 'set':775 'setup':40,695,953 'sever':232 'shape':264 'short':161 'silent':170 'singl':718 'single-test':717 'skill':28 'skill-writing-agents-md' 'smallest':691 'sourc':148 'source-narumiruna' 'specif':67,181,339,527,809 'specifi':456 'specul':541 'split':658 'stale':185,243 'standard':55 'state':640,721 'statement':788 'step':613,858 'still':932 'strict':774 'structur':615 'style':44,591,766,884 'subdirectori':460 'subproject':24,123,340 'suggest':238,270 'summar':560,618,1026 'summari':907 'symlink':928 'take':395 'target':709 'task':133 'tast':787 'teammat':600 'teammate-lik':599 'tell':862 'test':45,588,593,676,685,701,719,789,794,831 'testabl':373 'titl':469,482 'tool':444,771,930,946 'topic-agent-skills' 'treat':365 'tree':113 'true':838 'type':811 'typecheck':700 'ui':679,901 'uncertainti':158,197 'unless':476,525 'unsaf':248 'unverifi':187,434 'updat':16,173,377,830 'url':540 'use':5,260,466,480,505,712,866,959,1003,1031 'user':8,258,335,378,455,997 'usual':486 'variant':710 'vendor':118 'verif':517,564,707,791,906,1033 'verifi':129,272,289,356,974 'version':773 'walkthrough':433,524 'whether':648 'wide':664 'without':71 'word':489 'work':353,723 'workflow':77 'write':2,29,47,79 'writing-agents-md':1 'yaml':305","prices":[{"id":"a290397c-275b-47bd-bb4d-8e4bfba2e3f6","listingId":"c046237c-89bc-44d4-9a11-ccc771d2767b","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"narumiruna","category":"skills","install_from":"skills.sh"},"createdAt":"2026-05-18T19:13:47.856Z"}],"sources":[{"listingId":"c046237c-89bc-44d4-9a11-ccc771d2767b","source":"github","sourceId":"narumiruna/skills/writing-agents-md","sourceUrl":"https://github.com/narumiruna/skills/tree/main/skills/writing-agents-md","isPrimary":false,"firstSeenAt":"2026-05-18T19:13:47.856Z","lastSeenAt":"2026-05-18T19:13:47.856Z"}],"details":{"listingId":"c046237c-89bc-44d4-9a11-ccc771d2767b","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"narumiruna","slug":"writing-agents-md","github":{"repo":"narumiruna/skills","stars":7,"topics":["agent-skills"],"license":"mit","html_url":"https://github.com/narumiruna/skills","pushed_at":"2026-05-17T11:15:28Z","description":null,"skill_md_sha":"66d903ed7842ffc7a2a195acf2a6bdb3eec91b53","skill_md_path":"skills/writing-agents-md/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/narumiruna/skills/tree/main/skills/writing-agents-md"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"writing-agents-md","description":"Use when the user asks to create, review, audit, migrate, or update an AGENTS.md file for a repository, package, subproject, or monorepo. This skill writes agent-facing repository guidance grounded in project evidence, including setup, build/test commands, code style, testing, security, PR rules, nested AGENTS.md scope, and instruction precedence."},"skills_sh_url":"https://skills.sh/narumiruna/skills/writing-agents-md"},"updatedAt":"2026-05-18T19:13:47.856Z"}}