{"id":"f8e96906-73e8-467e-803d-1a61ef1e5c4a","shortId":"sXWqnA","kind":"skill","title":"claude-md-generator","tagline":"Use when the user asks to generate or update a project's CLAUDE or AGENTS context file from a codebase scan. Writes a focused file under 100 lines containing only the non-obvious build commands, conventions, and gotchas Claude Code needs.","description":"# CLAUDE.md Generator\n\nRead the codebase. Write a CLAUDE.md that tells Claude exactly what it needs: no more, no less.\n\n---\n\n**Critical rule:** A good CLAUDE.md is under 100 lines. It contains only information Claude cannot derive from reading the code itself. Do not auto-write the file: always show the draft and wait for user approval first.\n\n**Code snippet rule:** Never include inline code examples in CLAUDE.md. Instead use `file.ts:42` references. Code in CLAUDE.md wastes tokens and goes stale.\n\n---\n\n## Step 1: Detect Mode\n\nDetermine which of three modes to run:\n\n**create**: No CLAUDE.md exists. Write one from scratch.\n**update**: A CLAUDE.md exists. Improve it without discarding custom content.\n**audit**: Score all CLAUDE.md files in the project A-F and output a quality report. If the user says \"audit\", \"check\", \"review\", or \"grade\" my CLAUDE.md, run audit mode.\n\n```bash\n# Discover ALL CLAUDE.md locations\nfind . -name \"CLAUDE.md\" -not -path \"*/node_modules/*\" -not -path \"*/.git/*\" 2>/dev/null\nls ~/.claude/CLAUDE.md 2>/dev/null && echo \"Global CLAUDE.md found\"\nls .claude.local.md 2>/dev/null && echo \".claude.local.md found\"\n```\n\nIf multiple CLAUDE.md files are found: list them. Ask: \"Found CLAUDE.md in [locations]. Should I update all of them or just [root]?\"\n\n---\n\n## Step 2: Audit Mode (skip to Step 3 if create/update)\n\nFor each CLAUDE.md found, score it A-F using this rubric:\n\n| Criterion | What to check |\n|-----------|--------------|\n| Commands | Build/test/lint commands present and runnable? |\n| Architecture | Non-obvious structure explained? |\n| Non-obvious patterns | Gotchas, generated files, env var order documented? |\n| Conciseness | Under 100 lines? No obvious filler? |\n| Currency | Commands still match current package.json/Makefile? |\n| Actionability | Can a new contributor follow this without asking questions? |\n\nScore: 90-100 = A, 70-89 = B, 50-69 = C, 30-49 = D, 0-29 = F\n\nPresent as a table:\n\n```\n## CLAUDE.md Audit Report\n\n| File | Score | Grade | Top Issues |\n|------|-------|-------|-----------|\n| ./CLAUDE.md | 72 | B | Missing gotchas section, test command outdated |\n| ./packages/api/CLAUDE.md | 45 | D | No commands, 340 lines (too long), stale arch notes |\n\n**Overall: B (72/100)**\n\nIssues found:\n- ./packages/api/CLAUDE.md: 340 lines: well over the 100-line target\n- ./packages/api/CLAUDE.md: Test command references `jest` but package.json uses `vitest`\n- ./CLAUDE.md: No Gotchas section: most valuable section is missing\n```\n\nAfter the report, ask: \"Want me to fix any of these? (all / just root / specify)\"\n\nIf user says yes, continue to Step 3 for each file they want fixed.\n\n---\n\n## Step 3: Scan Project Structure\n\n```bash\n# Project type and package manager\nls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null\n\n# Top-level directory structure\nfind . -maxdepth 2 -type d \\\n  | grep -v node_modules | grep -v .git | grep -v __pycache__ \\\n  | grep -v \".next\" | grep -v dist | grep -v build | sort\n```\n\n---\n\n## Step 4: Extract Build and Test Commands\n\n```bash\n# npm/yarn/pnpm/bun scripts\ncat package.json 2>/dev/null \\\n  | python3 -c \"\nimport sys, json\nd = json.load(sys.stdin)\nfor name, cmd in d.get('scripts', {}).items():\n    print(f'{name}: {cmd}')\n\"\n\n# Python, Go, Rust Makefiles\ncat Makefile 2>/dev/null | grep -E \"^[a-z].*:\" | head -20\n\n# Go\ncat go.mod 2>/dev/null | head -5\n\n# Rust\ncat Cargo.toml 2>/dev/null | grep -E \"^\\[\" | head -10\n```\n\nIdentify the exact commands for: build, test (all), test (single file/name), dev server, lint/typecheck. Note any env vars required to run them.\n\n---\n\n## Step 5: Find Code Style and Gotchas\n\n```bash\n# Import aliases (most commonly missed)\npython3 -c \"\nimport json, sys\ntry:\n    d = json.load(open('tsconfig.json'))\n    paths = d.get('compilerOptions', {}).get('paths', {})\n    if paths: print('Import aliases:', json.dumps(paths, indent=2))\nexcept: pass\n\" 2>/dev/null\n\n# Environment variables required\ncat .env.example 2>/dev/null | grep -v \"^#\" | grep -v \"^$\" | head -20\n\n# Auto-generated files (must not be edited)\nfind . -path \"*/node_modules\" -prune -o -name \"*.ts\" -print \\\n  | xargs grep -l \"DO NOT EDIT\\|@generated\\|Generated by\" 2>/dev/null | head -5\n\n# Test setup requirements\ncat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30\n\n# Database/migration setup\nls migrations/ prisma/ drizzle/ db/ 2>/dev/null\n```\n\n**What counts as a Gotcha** (include these, skip everything else):\n- Files that are auto-generated (must not edit)\n- Env vars required BEFORE tests run\n- Non-default import alias mappings\n- Test commands that require a running service\n- Known intentional quirks (workarounds, not bugs)\n\n---\n\n## Step 6: Generate CLAUDE.md Draft with Gemini\n\nCompile all findings and generate the draft:\n\n```bash\ncat > /tmp/claude-md-request.json << 'ENDJSON'\n{\n  \"system_instruction\": {\n    \"parts\": [{\n      \"text\": \"Write a CLAUDE.md file for a software project. Rules: (1) Under 100 lines total. (2) Only include what Claude cannot derive from reading the code. (3) No inline code examples: use file.ts:42 references instead. (4) Sections: Commands, Code Style (only non-defaults), Testing (only if setup needed), Gotchas (required: what trips people up). Skip any section that has nothing non-obvious to say. (5) All commands in code blocks. (6) Preferred order: short Project Overview (1-2 sentences, only if non-obvious), Commands, Architecture (only non-obvious structure), Code Style, Testing, Gotchas. (7) Do not use em dashes. (8) Output only the CLAUDE.md content, no commentary.\"\n    }]\n  },\n  \"contents\": [{\n    \"parts\": [{\n      \"text\": \"PROJECT_ANALYSIS_HERE\"\n    }]\n  }],\n  \"generationConfig\": {\n    \"temperature\": 0.3,\n    \"maxOutputTokens\": 2048\n  }\n}\nENDJSON\n\ncurl -s -X POST \\\n  \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d @/tmp/claude-md-request.json \\\n  | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])\"\n```\n\nReplace `PROJECT_ANALYSIS_HERE` with findings from Steps 3-5.\n\n**For large projects (50+ files):** Add a `@path` pointer at the bottom of CLAUDE.md instead of inline detail:\n\n```markdown\n## Extended Reference\nSee @docs/ai-context/architecture.md for full module map.\nSee @docs/ai-context/testing.md for integration test setup details.\n```\n\nWrite the referenced files to `docs/ai-context/` with the detail that would not fit in 100 lines.\n\n---\n\n## Step 7: Self-QA\n\nBefore presenting the draft, check:\n\n- [ ] Under 100 lines (count: `echo \"$CONTENT\" | wc -l`)\n- [ ] No inline code examples (only `file.ts:42` references or shell commands)\n- [ ] All commands in code blocks and runnable as-is\n- [ ] Gotchas section present with at least one real entry\n- [ ] No section that says only things obvious from the files\n- [ ] No em dashes\n- [ ] No marketing words or filler phrases (\"This project uses React to...\")\n- [ ] Import aliases documented if they exist\n- [ ] Auto-generated files marked \"do not edit\" if they exist\n\nIf any check fails, revise before presenting.\n\n---\n\n## Step 8: Present Draft and Wait for Approval\n\n**Never write the file without user approval.**\n\nPresent the draft in a code block:\n\n```\n## Draft CLAUDE.md ([N] lines)\n\n[full draft content here]\n\n---\nWrite this to CLAUDE.md? (yes / edit first / cancel)\n```\n\nIf user says **yes**: write the file, then confirm:\n\"CLAUDE.md written ([N] lines). Sections: [list of ## headers].\"\n\nIf user says **edit first**: apply their edits, re-show the draft.\n\nIf user says **cancel**: stop.\n\n---\n\n## What NOT to Include\n\n- Language/framework version (\"This is a TypeScript project\")\n- How the framework works (Claude already knows React, FastAPI, etc.)\n- List of all dependencies\n- Style rules the linter already enforces (indent size, quote style)\n- Content that duplicates README.md\n- Inline code examples or multi-line snippets\n- Anything that would be identical for any project using the same stack","tags":["claude","generator","opendirectory","varnan-tech","agent-skills","gtm","hermes-agent","marketing-skills","openclaw-skills","skill-pack","skills","technical-seo"],"capabilities":["skill","source-varnan-tech","skill-claude-md-generator","topic-agent-skills","topic-gtm","topic-hermes-agent","topic-marketing-skills","topic-openclaw-skills","topic-skill-pack","topic-skills","topic-technical-seo"],"categories":["opendirectory"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Varnan-Tech/opendirectory/claude-md-generator","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Varnan-Tech/opendirectory","source_repo":"https://github.com/Varnan-Tech/opendirectory","install_from":"skills.sh"}},"qualityScore":"0.593","qualityRationale":"deterministic score 0.59 from registry signals: · indexed on github topic:agent-skills · 286 github stars · SKILL.md body (8,055 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-18T18:54:40.100Z","embedding":null,"createdAt":"2026-04-18T22:18:23.660Z","updatedAt":"2026-05-18T18:54:40.100Z","lastSeenAt":"2026-05-18T18:54:40.100Z","tsv":"'-10':537 '-100':314 '-2':807 '-20':521,613 '-29':326 '-30':653 '-49':323 '-5':528,642,890 '-69':320 '-89':317 '/.claude/claude.md':202 '/.git':198 '/claude.md':340,384 '/dev/null':200,204,212,443,487,514,526,533,600,607,640,651,662 '/makefile?':301 '/node_modules':195,624 '/packages/api/claude.md':349,366,375 '/tmp/claude-md-request.json':723,864 '/v1beta/models/gemini-2.0-flash:generatecontent?key=$gemini_api_key':857 '0':325,876,879 '0.3':847 '1':127,738,806 '100':31,73,289,372,740,939,952 '2':199,203,211,239,442,451,486,513,525,532,596,599,606,639,650,661,743 '2048':849 '3':245,415,423,754,889 '30':322 '340':354,367 '4':475,763 '45':350 '5':561,794 '50':319,894 '6':708,800 '7':825,942 '70':316 '72':341 '72/100':363 '8':831,1037 '90':313 'a-f':163,254 'a-z':517 'action':302 'add':896 'agent':19 'alia':692 'alias':569,592,1013 'alreadi':1125,1138 'alway':94 'analysi':843,883 'anyth':1156 'appli':1096 'application/json':862 'approv':102,1043,1050 'arch':359 'architectur':270,815 'as-i':976 'ask':9,224,310,396 'audit':155,175,183,240,333 'auto':90,615,677,1019 'auto-gener':614,676,1018 'auto-writ':89 'b':318,342,362 'bash':185,427,481,567,721 'block':799,973,1057 'bottom':902 'bug':706 'build':39,472,477,543 'build/test/lint':265 'bun.lockb':437 'c':321,489,574,866 'cancel':1073,1107 'candid':875 'cannot':80,748 'cargo.toml':440,531 'cat':484,511,523,530,604,646,722 'check':176,263,950,1031 'claud':2,17,44,57,79,747,1124 'claude-md-gener':1 'claude.local.md':210,214 'claude.md':47,54,70,113,120,139,147,158,181,188,192,207,218,226,250,332,710,731,835,904,1059,1069,1083 'cmd':498,506 'code':45,85,104,110,118,563,753,757,766,798,821,961,972,1056,1149 'codebas':24,51 'command':40,264,266,295,347,353,377,480,541,695,765,796,814,968,970 'commentari':838 'common':571 'compil':714 'compileropt':585 'concis':287 'confirm':1082 'contain':33,76 'content':154,836,839,860,877,956,1064,1144 'content-typ':859 'context':20 'continu':412 'contributor':306 'convent':41 'count':664,954 'creat':137 'create/update':247 'criterion':260 'critic':66 'curl':851 'currenc':294 'current':298 'custom':153 'd':324,351,453,493,579,863,870,874 'd.get':500,584 'dash':830,1000 'database/migration':654 'db':660 'default':690,771 'depend':1133 'deriv':81,749 'detail':908,924,933 'detect':128 'determin':130 'dev':549 'directori':447 'discard':152 'discov':186 'dist':469 'docs/ai-context':930 'docs/ai-context/architecture.md':913 'docs/ai-context/testing.md':919 'document':286,1014 'draft':97,711,720,949,1039,1053,1058,1063,1103 'drizzl':659 'duplic':1146 'e':516,535 'echo':205,213,955 'edit':621,635,681,1025,1071,1094,1098 'els':672 'em':829,999 'endjson':724,850 'enforc':1139 'entri':987 'env':283,554,682 'env.example':605 'environ':601 'etc':1129 'everyth':671 'exact':58,540 'exampl':111,758,962,1150 'except':597 'exist':140,148,1017,1028 'explain':275 'extend':910 'extract':476 'f':165,256,327,504 'fail':1032 'fastapi':1128 'file':21,29,93,159,219,282,335,418,617,673,732,895,928,997,1021,1047,1080 'file.ts:42':116,760,964 'file/name':548 'filler':293,1005 'find':190,449,562,622,716,886 'first':103,1072,1095 'fit':937 'fix':400,421 'focus':28 'follow':307 'found':208,215,221,225,251,365 'framework':1122 'full':915,1062 'gemini':713 'generat':4,11,48,281,616,636,637,678,709,718,1020 'generationconfig':845 'generativelanguage.googleapis.com':856 'generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generatecontent?key=$gemini_api_key':855 'get':586 'git':460 'global':206 'go':508,522 'go.mod':441,524 'goe':124 'good':69 'gotcha':43,280,344,386,566,667,777,824,979 'grade':179,337 'grep':454,458,461,464,467,470,515,534,608,610,631 'h':858 'head':520,527,536,612,641,652 'header':1090 'ident':1160 'identifi':538 'import':490,568,575,591,691,867,1012 'improv':149 'includ':108,668,745,1112 'indent':595,1140 'inform':78 'inlin':109,756,907,960,1148 'instead':114,762,905 'instruct':726 'integr':921 'intent':702 'issu':339,364 'item':502 'jest':379 'jest.config.js':647 'jest.config.ts':648 'json':492,576,869 'json.dumps':593 'json.load':494,580,871 'know':1126 'known':701 'l':632,958 'language/framework':1113 'larg':892 'least':984 'less':65 'level':446 'line':32,74,290,355,368,373,741,940,953,1061,1086,1154 'lint/typecheck':551 'linter':1137 'list':222,1088,1130 'locat':189,228 'long':357 'ls':201,209,433,656 'makefil':510,512 'manag':432 'map':693,917 'mark':1022 'markdown':909 'market':1002 'match':297 'maxdepth':450 'maxoutputtoken':848 'md':3 'migrat':657 'miss':343,392,572 'mode':129,134,184,241 'modul':457,916 'multi':1153 'multi-lin':1152 'multipl':217 'must':618,679 'n':1060,1085 'name':191,497,505,627 'need':46,61,776 'never':107,1044 'new':305 'next':466 'node':456 'non':37,272,277,689,770,790,812,818 'non-default':688,769 'non-obvi':36,271,276,789,811,817 'note':360,552 'noth':788 'npm/yarn/pnpm/bun':482 'o':626 'obvious':38,273,278,292,791,813,819,994 'one':142,985 'open':581 'order':285,802 'outdat':348 'output':167,832 'overal':361 'overview':805 'packag':431 'package.json':300,381,434,485 'package.json/makefile?':299 'part':727,840,878 'pass':598 'path':194,197,583,587,589,594,623,898 'pattern':279 'peopl':781 'phrase':1006 'pnpm-lock.yaml':436 'pointer':899 'post':854 'prefer':801 'present':267,328,947,981,1035,1038,1051 'print':503,590,629,873 'prisma':658 'project':15,162,425,428,736,804,842,882,893,1008,1119,1163 'prune':625 'pycach':463 'pyproject.toml':439 'python':507 'python3':488,573,865 'qa':945 'qualiti':169 'question':311 'quirk':703 'quot':1142 're':1100 're-show':1099 'react':1010,1127 'read':49,83,751 'readme.md':1147 'real':986 'refer':117,378,761,911,965 'referenc':927 'replac':881 'report':170,334,395 'requir':556,603,645,684,697,778 'requirements.txt':438 'review':177 'revis':1033 'root':237,406 'rubric':259 'rule':67,106,737,1135 'run':136,182,558,687,699 'runnabl':269,975 'rust':509,529 'say':174,410,793,991,1076,1093,1106 'scan':25,424 'score':156,252,312,336 'scratch':144 'script':483,501 'section':345,387,390,764,785,980,989,1087 'see':912,918 'self':944 'self-qa':943 'sentenc':808 'server':550 'servic':700 'setup':644,655,775,923 'shell':967 'short':803 'show':95,1101 'singl':547 'size':1141 'skill' 'skill-claude-md-generator' 'skip':242,670,783 'snippet':105,1155 'softwar':735 'sort':473 'source-varnan-tech' 'specifi':407 'stack':1167 'stale':125,358 'step':126,238,244,414,422,474,560,707,888,941,1036 'still':296 'stop':1108 'structur':274,426,448,820 'style':564,767,822,1134,1143 'sys':491,577,868 'sys.stdin':495,872 'system':725 'tabl':331 'target':374 'tell':56 'temperatur':846 'test':346,376,479,544,546,643,686,694,772,823,922 'text':728,841,880 'thing':993 'three':133 'token':122 'top':338,445 'top-level':444 'topic-agent-skills' 'topic-gtm' 'topic-hermes-agent' 'topic-marketing-skills' 'topic-openclaw-skills' 'topic-skill-pack' 'topic-skills' 'topic-technical-seo' 'total':742 'tri':578 'trip':780 'ts':628 'tsconfig.json':582 'type':429,452,861 'typescript':1118 'updat':13,145,231 'use':5,115,257,382,759,828,1009,1164 'user':8,101,173,409,1049,1075,1092,1105 'v':455,459,462,465,468,471,609,611 'valuabl':389 'var':284,555,683 'variabl':602 'version':1114 'vitest':383 'vitest.config.ts':649 'wait':99,1041 'want':397,420 'wast':121 'wc':957 'well':369 'without':151,309,1048 'word':1003 'work':1123 'workaround':704 'would':935,1158 'write':26,52,91,141,729,925,1045,1066,1078 'written':1084 'x':853 'xarg':630 'yarn.lock':435 'yes':411,1070,1077 'z':519","prices":[{"id":"dd368317-260e-4685-a070-3959e680e69a","listingId":"f8e96906-73e8-467e-803d-1a61ef1e5c4a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Varnan-Tech","category":"opendirectory","install_from":"skills.sh"},"createdAt":"2026-04-18T22:18:23.660Z"}],"sources":[{"listingId":"f8e96906-73e8-467e-803d-1a61ef1e5c4a","source":"github","sourceId":"Varnan-Tech/opendirectory/claude-md-generator","sourceUrl":"https://github.com/Varnan-Tech/opendirectory/tree/main/skills/claude-md-generator","isPrimary":false,"firstSeenAt":"2026-04-18T22:18:23.660Z","lastSeenAt":"2026-05-18T18:54:40.100Z"}],"details":{"listingId":"f8e96906-73e8-467e-803d-1a61ef1e5c4a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Varnan-Tech","slug":"claude-md-generator","github":{"repo":"Varnan-Tech/opendirectory","stars":286,"topics":["agent-skills","gtm","hermes-agent","marketing-skills","openclaw-skills","skill-pack","skills","technical-seo"],"license":"mit","html_url":"https://github.com/Varnan-Tech/opendirectory","pushed_at":"2026-05-18T18:27:10Z","description":" AI Agent Skills built for Founders who hate Marketing","skill_md_sha":"3ce28f79663776aaf833d96792261ed941dbc909","skill_md_path":"skills/claude-md-generator/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Varnan-Tech/opendirectory/tree/main/skills/claude-md-generator"},"layout":"multi","source":"github","category":"opendirectory","frontmatter":{"name":"claude-md-generator","description":"Use when the user asks to generate or update a project's CLAUDE or AGENTS context file from a codebase scan. Writes a focused file under 100 lines containing only the non-obvious build commands, conventions, and gotchas Claude Code needs.","compatibility":"[claude-code, gemini-cli, github-copilot]"},"skills_sh_url":"https://skills.sh/Varnan-Tech/opendirectory/claude-md-generator"},"updatedAt":"2026-05-18T18:54:40.100Z"}}