{"id":"08cbe3c5-7a55-439c-94f1-57c2fadfc00a","shortId":"aFyfQy","kind":"skill","title":"md-docs","tagline":">-","description":"# Markdown Documentation\n\nManage project documentation by verifying against actual codebase state. Emphasize verification over blind generation -- analyze structure, files, and patterns before writing.\n\n## Portability\n\nAGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). If the project uses CLAUDE.md, treat it as a symlink to AGENTS.md or migrate content into AGENTS.md and create the symlink:\n\n```bash\n# If CLAUDE.md exists and AGENTS.md doesn't\nmv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md\n```\n\nWhen this skill references \"context files\", it means AGENTS.md (and CLAUDE.md if present as symlink).\n\n## Workflows\n\n### Update Context Files\n\nVerify and fix AGENTS.md against the actual codebase. See [update-agents.md](./references/update-agents.md) for the full verification workflow.\n\n1. Read existing AGENTS.md, extract verifiable claims (paths, commands, structure, tooling)\n2. Verify each claim against codebase (`ls`, `cat package.json`, `cat pyproject.toml`, etc.)\n3. Fix discrepancies: outdated paths, wrong commands, missing sections, stale structure\n4. Discover undocumented patterns (scripts, build tools, test frameworks not yet documented)\n5. Report changes\n\n### Update README\n\nGenerate or refresh README.md from project metadata and structure. See [update-readme.md](./references/update-readme.md) for section templates and language-specific patterns.\n\n1. Detect language/stack from config files (package.json, pyproject.toml, composer.json)\n2. Extract metadata: name, version, description, license, scripts\n3. If README exists and `--preserve`: keep custom sections (About, Features), regenerate standard sections (Install, Usage)\n4. Generate sections appropriate to project type (library vs application)\n5. Report changes\n\n### Update CONTRIBUTING\n\nUpdate existing CONTRIBUTING.md only -- never auto-create. See [update-contributing.md](./references/update-contributing.md).\n\nWhen updating, detect project conventions automatically:\n- Package manager from lock files (package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb → bun)\n- Branch conventions from git history (feature/, fix/, chore/ prefixes)\n- Test commands from package.json scripts or pyproject.toml\n\n### Update DOCS\n\nIf `DOCS.md` exists, treat it as API-level documentation (endpoints, function signatures, type definitions). Verify against actual code the same way as AGENTS.md. Never auto-create DOCS.md -- only update existing.\n\n### Initialize Context\n\nCreate AGENTS.md from scratch for projects without documentation. See [init-agents.md](./references/init-agents.md).\n\n1. Analyze project: language, framework, structure, build/test tools\n2. Generate terse, expert-to-expert context sections\n3. Write AGENTS.md, create CLAUDE.md symlink\n\n## What Belongs in Context Files\n\nKeep AGENTS.md / CLAUDE.md to durable signal. Do NOT enumerate:\n\n- **Installed skills, plugins, or extensions** -- these change with the user's environment, not the project. The list rots within weeks and turns into a confusing catalog of names that may not be installed for the next reader.\n- **Tool versions outside the project's source of truth** -- `package.json` engines, `.nvmrc`, `pyproject.toml` Python constraint, `composer.json` PHP version. List the source-of-truth file path; do not duplicate the version inline.\n- **Linter / formatter rule restatements** -- if `.eslintrc`, `ruff.toml`, `phpcs.xml` already enforce it, the file is the spec. List the command to run; do not paraphrase rules.\n- **README content** -- if information is already in README.md (install, badges, intro), reference it; do not re-paste.\n\nThe test: if a fact will be wrong in two months without anyone touching this file, it does not belong here. The file is for project-specific rules that survive tool churn.\n\n## Context File Hierarchy\n\nStructure CLAUDE.md (and AGENTS.md) content by priority so the most critical information loads first when context is compacted:\n\n1. **Rules** -- project constraints, forbidden patterns, required conventions. Override everything else.\n2. **Tech stack** -- languages, frameworks, package managers. For exact versions, point at the project's source-of-truth file (`package.json` engines, `.nvmrc`, `pyproject.toml`, `composer.json`); do not duplicate the version inline.\n3. **Commands** -- how to build, test, lint, deploy. Exact commands, not descriptions.\n4. **Conventions** -- naming patterns, file organization, architectural decisions.\n5. **Boundaries** -- what's off-limits, what requires approval, scope constraints.\n\nRules that prevent mistakes outweigh background information. Place them at the top so they survive aggressive context compaction.\n\n## Monorepo Context Loading\n\nClaude Code's context-file loading in monorepos follows three rules -- understanding them determines where content belongs:\n\n- **Ancestors load immediately**: walking UP from the current working directory, every AGENTS.md / CLAUDE.md encountered is loaded at startup. Put shared conventions at the repo root.\n- **Descendants load lazily**: an AGENTS.md deeper in the tree loads only when Claude reads or edits a file inside that subtree. Put package-specific conventions at each package's root (`packages/api/AGENTS.md`, `apps/web/AGENTS.md`).\n- **Siblings never load**: `packages/a/AGENTS.md` will NOT auto-load when working in `packages/b/`. Do not rely on sibling-package context leaking across.\n\nImplication for monorepo layouts: duplicate any rule that must apply across sibling packages into each package's AGENTS.md (or hoist it to the repo root). The loader will not discover it laterally. Conversely, avoid putting package-specific rules at the root -- they'll load into every session regardless of relevance and burn context.\n\n## Arguments\n\nAll workflows support:\n\n- `--dry-run`: preview changes without writing\n- `--preserve`: keep existing structure, fix inaccuracies only\n- `--minimal`: quick pass, high-level structure only\n- `--thorough`: deep analysis of all files\n\n## Backup Handling\n\nBefore overwriting, back up existing files:\n\n```bash\ncp AGENTS.md AGENTS.md.backup\ncp README.md README.md.backup\n```\n\nNever delete backups automatically.\n\n## Writing Style\n\n- **Lead with the answer.** First sentence of each section states the conclusion; reasoning follows. No \"In this section, we'll...\" preamble.\n- **Imperative form** for instructions: \"Build the project\" not \"The project is built\" — verify no passive voice in any directive sentence.\n- **Expert-to-expert**: cut explanations of concepts the target reader already knows. For CLAUDE.md/AGENTS.md, assume familiarity with git, package managers, test runners, and the project's main language.\n- **Scannable**: headings every ~20 lines, bullet lists for ≥3 parallel items, fenced code blocks for every command.\n- **Verify every command and path against the codebase.** Run each command before committing; grep for each referenced path. Stale paths and untested commands are the most common doc defect.\n- **Sentence case headings**, no emoji decoration (exception: changelog entries may use emoji per project convention).\n- **Actionable headings**: \"Set SAML before adding users\" — not \"SAML configuration timing\". Reader should know what to do from the heading alone.\n- **Collapse depth** with `<details>` blocks instead of deleting content (blank line required after `<summary>` for GitHub rendering).\n\n## README Anti-Patterns\n\nFlag during `Update README` workflows:\n- Framework-first lead (explaining the tech stack before the problem it solves)\n- Jargon before definition (using project-specific terms without introduction)\n- Theory before try (architecture explanation before a working example)\n- Claims without evidence (\"blazingly fast\" with no benchmarks)\n\n## Report Format\n\nAfter every operation, display a summary:\n\n```\n[OK] Updated AGENTS.md\n  - Fixed build command\n  - Added new directory to structure\n\n[OK] Updated README.md\n  - Added installation section\n  - Updated badges\n\n[--] CONTRIBUTING.md not found (skipped)\n```\n\n## Verify\n\n- Every factual claim in updated docs verified against current codebase\n- No stale file paths or component names\n- Formatting renders correctly in markdown preview","tags":["docs","skills","iliaal","agent-skills","ai-coding-assistant","ai-tools","claude-code"],"capabilities":["skill","source-iliaal","skill-md-docs","topic-agent-skills","topic-ai-coding-assistant","topic-ai-tools","topic-claude-code","topic-skills"],"categories":["ai-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/iliaal/ai-skills/md-docs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add iliaal/ai-skills","source_repo":"https://github.com/iliaal/ai-skills","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 13 github stars · SKILL.md body (8,196 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:07:02.505Z","embedding":null,"createdAt":"2026-05-09T01:05:35.513Z","updatedAt":"2026-05-18T19:07:02.505Z","lastSeenAt":"2026-05-18T19:07:02.505Z","tsv":"'/agents.md,':884 '/references/init-agents.md':322 '/references/update-agents.md':105 '/references/update-contributing.md':240 '/references/update-readme.md':173 '1':111,182,323,526 '2':122,191,331,537 '20':902 '3':134,199,340,568,907 '4':145,215,580 '5':157,225,588 'across':719,730 'action':960 'actual':12,101,295 'ad':965,1059,1067 'agents.md':28,51,56,66,71,74,84,98,114,301,313,342,352,511,650,668,737,816,1055 'agents.md.backup':817 'aggress':615 'alon':980 'alreadi':437,459,879 'analysi':802 'analyz':20,324 'ancestor':639 'answer':830 'anti':998 'anti-pattern':997 'anyon':484 'api':285 'api-level':284 'appli':729 'applic':224 'appropri':218 'approv':597 'apps/web/agents.md':696 'architectur':586,1031 'argument':774 'assum':885 'auto':236,304,704 'auto-cr':235,303 'auto-load':703 'automat':246,824 'avoid':753 'back':810 'background':605 'backup':806,823 'badg':463,1071 'bash':61,814 'belong':347,491,638 'benchmark':1044 'blank':989 'blaze':1040 'blind':18 'block':912,984 'boundari':589 'branch':260 'build':150,572,852,1057 'build/test':329 'built':859 'bullet':904 'bun':259 'bun.lockb':258 'burn':772 'case':946 'cat':129,131 'catalog':385 'chang':159,227,366,782 'changelog':952 'chore':267 'churn':504 'claim':117,125,1037,1079 'claud':36,621,676 'claude.md':44,63,70,75,86,344,353,509,651,883 'claude.md/agents.md,':882 'code':37,296,622,911 'codebas':13,102,127,923,1086 'codex':38 'collaps':981 'command':119,140,270,447,569,577,915,918,926,938,1058 'commit':928 'common':942 'compact':525,617 'compon':1092 'composer.json':190,412,561 'concept':875 'conclus':838 'config':186 'configur':969 'confus':384 'constraint':411,529,599 'content':54,455,512,637,988 'context':32,80,93,311,338,349,505,523,616,619,625,717,773 'context-fil':624 'contribut':229 'contributing.md':232,1072 'convent':245,261,533,581,659,689,959 'convers':752 'correct':1096 'cp':815,818 'creat':58,237,305,312,343 'critic':518 'current':646,1085 'custom':206 'cut':872 'decis':587 'decor':950 'deep':801 'deeper':669 'defect':944 'definit':292,1020 'delet':822,987 'deploy':575 'depth':982 'descend':664 'descript':196,579 'detect':183,243 'determin':635 'direct':866 'directori':648,1061 'discov':146,749 'discrep':136 'display':1050 'doc':3,277,943,1082 'docs.md':279,306 'document':5,8,156,287,319 'doesn':67 'dri':779 'dry-run':778 'duplic':425,564,724 'durabl':355 'edit':679 'els':536 'emoji':949,956 'emphas':15 'encount':652 'endpoint':288 'enforc':438 'engin':407,558 'entri':953 'enumer':359 'environ':371 'eslintrc':434 'etc':133 'everi':649,766,901,914,917,1048,1077 'everyth':535 'evid':1039 'exact':545,576 'exampl':1036 'except':951 'exist':64,113,202,231,280,309,787,812 'expert':335,337,869,871 'expert-to-expert':334,868 'explain':1009 'explan':873,1032 'extens':364 'extract':115,192 'fact':476 'factual':1078 'familiar':886 'fast':1041 'featur':209,265 'fenc':910 'file':22,33,81,94,187,251,350,421,441,487,494,506,556,584,626,681,805,813,1089 'first':521,831,1007 'fix':97,135,266,789,1056 'flag':1000 'follow':630,840 'forbidden':530 'form':849 'format':1046,1094 'formatt':430 'found':1074 'framework':153,327,541,1006 'framework-first':1005 'full':108 'function':289 'generat':19,162,216,332 'git':263,888 'github':994 'grep':929 'handl':807 'head':900,947,961,979 'hierarchi':507 'high':796 'high-level':795 'histori':264 'hoist':739 'immedi':641 'imper':848 'implic':720 'inaccuraci':790 'inform':457,519,606 'init-agents.md':321 'initi':310 'inlin':428,567 'insid':682 'instal':213,360,392,462,1068 'instead':985 'instruct':851 'intro':464 'introduct':1027 'item':909 'jargon':1018 'keep':205,351,786 'kilocod':39 'know':880,973 'languag':179,326,540,898 'language-specif':178 'language/stack':184 'later':751 'layout':723 'lazili':666 'lead':827,1008 'leak':718 'level':286,797 'librari':222 'licens':197 'limit':594 'line':903,990 'lint':574 'linter':429 'list':376,415,445,905 'll':763,846 'ln':72 'load':520,620,627,640,654,665,673,699,705,764 'loader':746 'lock':250 'ls':128 'main':897 'manag':6,248,543,890 'markdown':4,1098 'may':389,954 'md':2 'md-doc':1 'mean':83 'metadata':168,193 'migrat':53 'minim':792 'miss':141 'mistak':603 'monorepo':618,629,722 'month':482 'must':728 'mv':69 'name':194,387,582,1093 'never':234,302,698,821 'new':1060 'next':395 'npm':253 'nvmrc':408,559 'off-limit':592 'ok':1053,1064 'oper':1049 'organ':585 'outdat':137 'outsid':399 'outweigh':604 'overrid':534 'overwrit':809 'packag':247,542,687,692,716,732,735,756,889 'package-lock.json':252 'package-specif':686,755 'package.json':130,188,272,406,557 'packages/a/agents.md':700 'packages/api/agents.md':695 'packages/b':709 'parallel':908 'paraphras':452 'pass':794 'passiv':862 'past':471 'path':118,138,422,920,933,935,1090 'pattern':24,148,181,531,583,999 'per':957 'php':413 'phpcs.xml':436 'place':607 'plugin':362 'pnpm':257 'pnpm-lock.yaml':256 'point':547 'portabl':27 'preambl':847 'prefix':268 'present':88 'preserv':204,785 'prevent':602 'preview':781,1099 'prioriti':514 'problem':1015 'project':7,42,167,220,244,317,325,374,401,498,528,550,854,857,895,958,1023 'project-specif':497,1022 'put':657,685,754 'pyproject.toml':132,189,275,409,560 'python':410 'quick':793 're':470 're-past':469 'read':112,677 'reader':396,878,971 'readm':161,201,454,996,1003 'readme.md':165,461,819,1066 'readme.md.backup':820 'reason':839 'refer':79,465 'referenc':932 'refresh':164 'regardless':768 'regener':210 'relev':770 'reli':712 'render':995,1095 'repo':662,743 'report':158,226,1045 'requir':532,596,991 'restat':432 'root':663,694,744,761 'rot':377 'ruff.toml':435 'rule':431,453,500,527,600,632,726,758 'run':449,780,924 'runner':892 'saml':963,968 'scannabl':899 'scope':598 'scratch':315 'script':149,198,273 'section':142,175,207,212,217,339,835,844,1069 'see':103,171,238,320 'sentenc':832,867,945 'session':767 'set':962 'sf':73 'share':658 'sibl':697,715,731 'sibling-packag':714 'signal':356 'signatur':290 'skill':78,361 'skill-md-docs' 'skip':1075 'solv':1017 'sourc':403,418,553 'source-iliaal' 'source-of-truth':417,552 'spec':444 'specif':180,499,688,757,1024 'stack':539,1012 'stale':143,934,1088 'standard':211 'startup':656 'state':14,836 'structur':21,120,144,170,328,508,788,798,1063 'style':826 'subtre':684 'summari':1052 'support':777 'surviv':502,614 'symlink':49,60,90,345 'target':877 'tech':538,1011 'templat':176 'term':1025 'ters':333 'test':152,269,473,573,891 'theori':1028 'thorough':800 'three':631 'time':970 'tool':121,151,330,397,503 'top':611 'topic-agent-skills' 'topic-ai-coding-assistant' 'topic-ai-tools' 'topic-claude-code' 'topic-skills' 'touch':485 'treat':45,281 'tree':672 'tri':1030 'truth':405,420,555 'turn':381 'two':481 'type':221,291 'understand':633 'undocu':147 'univers':31 'untest':937 'updat':92,160,228,230,242,276,308,1002,1054,1065,1070,1081 'update-agents.md':104 'update-contributing.md':239 'update-readme.md':172 'usag':214 'use':43,955,1021 'user':369,966 'verif':16,109 'verifi':10,95,116,123,293,860,916,1076,1083 'version':195,398,414,427,546,566 'voic':863 'vs':223 'walk':642 'way':299 'week':379 'within':378 'without':318,483,783,1026,1038 'work':34,647,707,1035 'workflow':91,110,776,1004 'write':26,341,784,825 'wrong':139,479 'yarn':255 'yarn.lock':254 'yet':155","prices":[{"id":"f4444be2-06e5-42ea-af6b-ade8f4392be0","listingId":"08cbe3c5-7a55-439c-94f1-57c2fadfc00a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"iliaal","category":"ai-skills","install_from":"skills.sh"},"createdAt":"2026-05-09T01:05:35.513Z"}],"sources":[{"listingId":"08cbe3c5-7a55-439c-94f1-57c2fadfc00a","source":"github","sourceId":"iliaal/ai-skills/md-docs","sourceUrl":"https://github.com/iliaal/ai-skills/tree/master/skills/md-docs","isPrimary":false,"firstSeenAt":"2026-05-09T01:05:35.513Z","lastSeenAt":"2026-05-18T19:07:02.505Z"}],"details":{"listingId":"08cbe3c5-7a55-439c-94f1-57c2fadfc00a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"iliaal","slug":"md-docs","github":{"repo":"iliaal/ai-skills","stars":13,"topics":["agent-skills","ai-coding-assistant","ai-tools","claude-code","skills"],"license":"mit","html_url":"https://github.com/iliaal/ai-skills","pushed_at":"2026-05-16T13:15:17Z","description":"Curated collection of agent skills for AI coding assistants.","skill_md_sha":"60aaf9bef7d6b451d3f3f0edb4d107323b6ed7f0","skill_md_path":"skills/md-docs/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/iliaal/ai-skills/tree/master/skills/md-docs"},"layout":"multi","source":"github","category":"ai-skills","frontmatter":{"name":"md-docs","description":">-"},"skills_sh_url":"https://skills.sh/iliaal/ai-skills/md-docs"},"updatedAt":"2026-05-18T19:07:02.505Z"}}