{"id":"c756b53e-7788-49aa-96b0-3879fb09ac9e","shortId":"TYXY6Y","kind":"skill","title":"harness-step1-create-agents-md","tagline":"Harness Engineering 第一阶段：扫描现有项目，生成 AGENTS.md（目录文件）和完整的 docs/ 知识库结构。\n\n当用户想要\"为项目添加 agent 支持\"、\"让 AI 更好地理解我的项目\"、\"开始 harness engineering\"、\n\"创建 AGENTS.md\"、\"搭建 agent 文档结构\"、\"让 Claude Code 更好地工作\"时，立即使用此 skill。\n\n也适用于用户说\"帮我把项目文档整理好给 agent 用\"、\"我想开始用 AI agent 开发\"等场景。","description":"# Harness Step 1: 创建 AGENTS.md 与 docs/ 知识库\n\n## 目标\n\n为项目建立 agent 可读的知识库地基：\n- 一份简短的 `AGENTS.md`（~100 行，作为\"目录\"而非百科全书）\n- 一套 `docs/` 目录结构，存放真正的知识\n\n**核心原则**：agent 看不到的东西就不存在。所有架构决策、命名约定、技术选型，必须以文件形式存在于仓库中。\n\n---\n\n## 执行步骤\n\n### Step 1：扫描项目\n\n按顺序收集项目信息，**已知信息跳过，不要重复提问**：\n\n```bash\n# 1. 项目根目录结构（2层）\nfind . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' \\\n  -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/.next/*' | sort\n\n# 2. 识别技术栈\ncat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \\\n  cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null || echo \"未找到包管理文件\"\n\n# 3. 查看是否已有文档\nls -la *.md 2>/dev/null; ls -la docs/ 2>/dev/null\n\n# 4. 查看 README（如有）\nhead -80 README.md 2>/dev/null || head -80 readme.md 2>/dev/null\n```\n\n从扫描结果中提取：\n- **项目名称和用途**（从 README 或 package.json）\n- **技术栈**（语言、框架、主要依赖）\n- **目录结构**（主要模块划分）\n- **已有文档**（避免重复，复用现有内容）\n\n### Step 2：生成 docs/ 目录结构\n\n创建以下文件（内容根据扫描结果填写，不要留空占位符）：\n\n**必须创建的文件：**\n\n```\nAGENTS.md                    ← 目录文件，~100行\ndocs/\n├── ARCHITECTURE.md          ← 模块划分、依赖关系\n├── CONVENTIONS.md           ← 命名规则、代码风格\n├── TECH_DECISIONS.md        ← 技术选型理由\n├── QUALITY.md               ← 验收标准、完成定义\n└── exec-plans/\n    ├── active/              ← 当前进行中的计划（空目录，放 .gitkeep）\n    ├── completed/           ← 已完成的计划（空目录，放 .gitkeep）\n    ├── backlog.md           ← 待开发功能列表（已知需求，尚未排期）\n    └── tech-debt-tracker.md ← 已知技术债务\n```\n\n**可选创建（根据项目实际情况判断）：**\n\n```\ndocs/\n├── design-docs/             ← 有复杂设计决策时创建\n├── product-specs/           ← 有产品规格时创建\n└── references/              ← 有外部文档需要本地化时创建\n```\n\n### Step 3：写 AGENTS.md\n\n严格遵守以下格式，控制在 100 行以内：\n\n```markdown\n# [项目名称] — Agent 工作指南\n\n## 这是什么项目\n[1-3句话：项目用途、核心功能、服务对象]\n\n## 快速定向\n- **我在哪个目录？** 运行 `pwd` 确认工作目录\n- **技术栈**：[语言] + [框架] + [主要工具]\n- **入口文件**：[主要入口，如 src/main.ts、app/main.py]\n- **启动命令**：[如何启动开发服务器]\n- **测试命令**：[如何跑测试]\n\n## 知识库地图\n在做任何修改前，先阅读相关文档：\n\n| 我想了解... | 去读这个文件 |\n|------------|-------------|\n| 整体架构、模块划分 | `docs/ARCHITECTURE.md` |\n| 命名规则、代码风格 | `docs/CONVENTIONS.md` |\n| 技术选型原因 | `docs/TECH_DECISIONS.md` |\n| 什么叫\"完成\" | `docs/QUALITY.md` |\n| 当前进行中的计划 | `docs/exec-plans/active/` |\n| 待开发功能列表 | `docs/exec-plans/backlog.md` |\n| 已知技术债务 | `docs/exec-plans/tech-debt-tracker.md` |\n\n## 工作规范\n1. **改之前先读**：修改任何模块前，先读对应的架构文档\n2. **完成即提交**：每个功能完成后立即 git commit，写清楚做了什么\n3. **更新文档**：如果你的修改影响了架构或约定，同步更新 docs/\n4. **不要猜**：看不懂的地方先读文档，文档没有再问\n\n## 禁止事项\n[根据项目实际情况填写，例如：]\n- 不要直接修改 `generated/` 目录下的文件（自动生成）\n- 不要跳过测试直接合并\n- 不要在 service 层引用 UI 组件（见 docs/ARCHITECTURE.md）\n```\n\n### Step 4：写各个 docs/ 文件\n\n每个文件的内容要求：\n\n**`docs/ARCHITECTURE.md`**\n- 模块/包的划分和职责\n- 依赖方向规则（哪层能引用哪层）\n- 主要数据流\n- 不要写实现细节，写\"是什么\"和\"为什么这样分\"\n\n**`docs/CONVENTIONS.md`**\n- 文件命名规则\n- 变量/函数/类命名规则\n- 目录组织规则\n- 注释风格\n- 任何团队约定俗成的习惯\n\n**`docs/TECH_DECISIONS.md`**\n- 为什么选这个框架而不是其他\n- 为什么用这个库\n- 历史上做过的重要架构决定和原因\n- 如果扫描时无法判断原因，写\"待补充\"并注明这是需要人工填写的\n\n**`docs/QUALITY.md`**\n- 一个功能算\"完成\"的标准（Definition of Done）\n- 代码审查检查清单\n- 测试覆盖要求\n- 性能基准（如果有）\n\n**`docs/exec-plans/backlog.md`**\n- 已知但尚未排期的待开发功能列表，这一点可以向用户询问\n- 每条格式：`[优先级: P1/P2/P3] 功能描述 — 背景说明`\n- 注意：backlog 是\"想做但还没做\"，不是技术债务（技术债务是\"已有但做得不好\"）\n- 如果扫描时发现后端已实现但前端未上线的功能、或文档中提到的计划中功能，写入此处\n- 如果扫描时没有发现明显的 backlog，写空列表并注明\"待发现时补充\"\n\n**`docs/exec-plans/tech-debt-tracker.md`**\n- 已知的技术债务列表（现有代码中质量不佳、需要改进的部分）\n- 每条格式：`[优先级] 问题描述 — 影响范围`\n- 注意：不要把 backlog（待开发功能）混入此文件\n- 如果扫描时没有发现明显债务，写空列表并注明\"待发现时补充\"\n\n---\n\n## 质量检验\n\n生成完成后，自检以下问题：\n\n- [ ] AGENTS.md 是否控制在 150 行以内？\n- [ ] AGENTS.md 里是否有具体的启动/测试命令（而非\"见文档\"）？\n- [ ] docs/ 里的文件是否有实际内容，而非空占位符？\n- [ ] TECH_DECISIONS.md 里无法判断的决策是否标注了\"待补充\"？\n- [ ] 目录表里的每个链接是否对应实际存在的文件？\n\n---\n\n## 完成后告知用户\n\n输出一个简短摘要：\n1. 创建了哪些文件\n2. 哪些内容是从项目扫描中推断的（可能需要人工核实）\n3. 哪些字段需要用户手动补充（标注了\"待补充\"的地方）\n4. 下一步：可以运行 `harness-step2` skill 来建立状态管理（progress 文件 + tasks.json）","tags":["harness","step1","create","agent","book2skills","simbajigege","agent-skills","agentskills","anthropic","anthropic-claude","growth-investing","investing"],"capabilities":["skill","source-simbajigege","skill-harness-step1-create-agent-md","topic-agent-skills","topic-agentskills","topic-anthropic","topic-anthropic-claude","topic-book2skills","topic-growth-investing","topic-investing","topic-investing-skills","topic-skills","topic-stock-analysis"],"categories":["book2skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/simbajigege/book2skills/harness-step1-create-agent-md","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add simbajigege/book2skills","source_repo":"https://github.com/simbajigege/book2skills","install_from":"skills.sh"}},"qualityScore":"0.468","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 36 github stars · SKILL.md body (3,605 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-01T12:56:53.919Z","embedding":null,"createdAt":"2026-04-18T22:21:58.547Z","updatedAt":"2026-05-01T12:56:53.919Z","lastSeenAt":"2026-05-01T12:56:53.919Z","tsv":"'-3':239 '-80':145,150 '/.git':97 '/.next':106 '/__pycache__':100 '/dev/null':113,117,121,125,134,139,148,153 '/dist':103 '/node_modules':94 '1':50,80,86,238,285,422 '100':62,231 '100行':180 '150':406 '2':91,108,112,116,120,124,133,138,147,152,170,289,424 '2层':88 '3':128,226,295,427 '4':140,300,320,432 'activ':196 'agent':5,19,30,41,45,58,72,235 'agents.md':12,28,52,61,178,228,404,408 'ai':22,44 'app/main.py':257 'architecture.md':182 'backlog':372,382,395 'backlog.md':206 'bash':85 'cargo.toml':123 'cat':110,114,118,122 'claud':33 'code':34 'commit':293 'complet':201 'conventions.md':185 'creat':4 'definit':356 'design':216 'design-doc':215 'doc':15,54,68,137,172,181,214,217,299,322,413 'docs/architecture.md':269,318,325 'docs/conventions.md':272,336 'docs/exec-plans/active':279 'docs/exec-plans/backlog.md':281,363 'docs/exec-plans/tech-debt-tracker.md':283,385 'docs/quality.md':277,352 'docs/tech_decisions.md':274,344 'done':358 'echo':126 'engin':8,26 'exec':194 'exec-plan':193 'find':89 'generat':308 'git':292 'gitkeep':200,205 'go.mod':119 'har':2,7,25,48,436 'harness-step1-create-agents-md':1 'harness-step2':435 'head':144,149 'la':131,136 'ls':130,135 'markdown':233 'maxdepth':90 'md':6,132 'p1/p2/p3':368 'package.json':111,159 'path':93,96,99,102,105 'plan':195 'product':220 'product-spec':219 'progress':440 'pwd':247 'pyproject.toml':115 'quality.md':190 'readm':142,157 'readme.md':146,151 'refer':223 'servic':313 'skill':38,438 'skill-harness-step1-create-agent-md' 'sort':107 'source-simbajigege' 'spec':221 'src/main.ts':256 'step':49,79,169,225,319 'step1':3 'step2':437 'tasks.json':442 'tech-debt-tracker.md':210 'tech_decisions.md':188,416 'topic-agent-skills' 'topic-agentskills' 'topic-anthropic' 'topic-anthropic-claude' 'topic-book2skills' 'topic-growth-investing' 'topic-investing' 'topic-investing-skills' 'topic-skills' 'topic-stock-analysis' 'ui':315 '一个功能算':353 '一份简短的':60 '一套':67 '下一步':433 '不是技术债务':375 '不要写实现细节':331 '不要在':312 '不要把':394 '不要猜':301 '不要留空占位符':176 '不要直接修改':307 '不要跳过测试直接合并':311 '不要重复提问':84 '与':53 '严格遵守以下格式':229 '为什么用这个库':346 '为什么这样分':335 '为什么选这个框架而不是其他':345 '为项目建立':57 '为项目添加':18 '主要依赖':163 '主要入口':254 '主要工具':252 '主要数据流':330 '主要模块划分':165 '也适用于用户说':39 '什么叫':275 '从':156 '从扫描结果中提取':154 '代码审查检查清单':359 '代码风格':187,271 '任何团队约定俗成的习惯':343 '优先级':367,390 '作为':64 '例如':306 '依赖关系':184 '依赖方向规则':328 '修改任何模块前':287 '先读对应的架构文档':288 '先阅读相关文档':264 '入口文件':253 '内容根据扫描结果填写':175 '写':227,332,349 '写入此处':380 '写各个':321 '写清楚做了什么':294 '写空列表并注明':383,399 '函数':339 '创建':27,51 '创建了哪些文件':423 '创建以下文件':174 '功能描述':369 '包的划分和职责':327 '历史上做过的重要架构决定和原因':347 '去读这个文件':266 '变量':338 '句话':240 '可以运行':434 '可能需要人工核实':426 '可读的知识库地基':59 '可选创建':212 '同步更新':298 '启动命令':258 '命名约定':75 '命名规则':186,270 '和':334 '和完整的':14 '哪些内容是从项目扫描中推断的':425 '哪些字段需要用户手动补充':428 '哪层能引用哪层':329 '在做任何修改前':263 '复用现有内容':168 '如':255 '如何启动开发服务器':259 '如何跑测试':261 '如有':143 '如果你的修改影响了架构或约定':297 '如果扫描时发现后端已实现但前端未上线的功能':378 '如果扫描时无法判断原因':348 '如果扫描时没有发现明显债务':398 '如果扫描时没有发现明显的':381 '如果有':362 '存放真正的知识':70 '完成':276,354 '完成即提交':290 '完成后告知用户':420 '完成定义':192 '尚未排期':209 '层引用':314 '工作指南':236 '工作规范':284 '已完成的计划':202 '已有但做得不好':377 '已有文档':166 '已知但尚未排期的待开发功能列表':364 '已知信息跳过':83 '已知技术债务':211,282 '已知的技术债务列表':386 '已知需求':208 '帮我把项目文档整理好给':40 '并注明这是需要人工填写的':351 '开发':46 '开始':24 '当前进行中的计划':197,278 '当用户想要':17 '影响范围':392 '待发现时补充':384,400 '待开发功能':396 '待开发功能列表':207,280 '待补充':350,418,430 '必须以文件形式存在于仓库中':77 '必须创建的文件':177 '快速定向':244 '性能基准':361 '想做但还没做':374 '我在哪个目录':245 '我想了解':265 '我想开始用':43 '或':158 '或文档中提到的计划中功能':379 '所有架构决策':74 '执行步骤':78 '扫描现有项目':10 '扫描项目':81 '技术债务是':376 '技术栈':160,249 '技术选型':76 '技术选型原因':273 '技术选型理由':189 '按顺序收集项目信息':82 '控制在':230 '搭建':29 '支持':20 '改之前先读':286 '放':199,204 '整体架构':267 '文件':323,441 '文件命名规则':337 '文档没有再问':303 '文档结构':31 '时':36 '是':373 '是什么':333 '是否控制在':405 '更好地工作':35 '更好地理解我的项目':23 '更新文档':296 '有产品规格时创建':222 '有复杂设计决策时创建':218 '有外部文档需要本地化时创建':224 '服务对象':243 '未找到包管理文件':127 '来建立状态管理':439 '查看':141 '查看是否已有文档':129 '标注了':429 '核心功能':242 '核心原则':71 '根据项目实际情况判断':213 '根据项目实际情况填写':305 '框架':162,251 '模块':326 '模块划分':183,268 '每个功能完成后立即':291 '每个文件的内容要求':324 '每条格式':366,389 '注意':371,393 '注释风格':342 '测试命令':260,410 '测试覆盖要求':360 '混入此文件':397 '现有代码中质量不佳':387 '生成':11,171 '生成完成后':402 '用':42 '的地方':431 '的标准':355 '目录':65 '目录下的文件':309 '目录文件':13,179 '目录组织规则':341 '目录结构':69,164,173 '目录表里的每个链接是否对应实际存在的文件':419 '目标':56 '看不到的东西就不存在':73 '看不懂的地方先读文档':302 '知识库':55 '知识库地图':262 '知识库结构':16 '确认工作目录':248 '禁止事项':304 '空目录':198,203 '立即使用此':37 '第一阶段':9 '等场景':47 '类命名规则':340 '组件':316 '而非':411 '而非百科全书':66 '而非空占位符':415 '背景说明':370 '自动生成':310 '自检以下问题':403 '行':63 '行以内':232,407 '见':317 '见文档':412 '让':21,32 '识别技术栈':109 '语言':161,250 '质量检验':401 '输出一个简短摘要':421 '运行':246 '这一点可以向用户询问':365 '这是什么项目':237 '避免重复':167 '里无法判断的决策是否标注了':417 '里是否有具体的启动':409 '里的文件是否有实际内容':414 '问题描述':391 '需要改进的部分':388 '项目名称':234 '项目名称和用途':155 '项目根目录结构':87 '项目用途':241 '验收标准':191","prices":[{"id":"1696f3a9-16c2-468b-8ad7-de71e9e629bb","listingId":"c756b53e-7788-49aa-96b0-3879fb09ac9e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"simbajigege","category":"book2skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:58.547Z"}],"sources":[{"listingId":"c756b53e-7788-49aa-96b0-3879fb09ac9e","source":"github","sourceId":"simbajigege/book2skills/harness-step1-create-agent-md","sourceUrl":"https://github.com/simbajigege/book2skills/tree/main/skills/harness-step1-create-agent-md","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:58.547Z","lastSeenAt":"2026-05-01T12:56:53.919Z"}],"details":{"listingId":"c756b53e-7788-49aa-96b0-3879fb09ac9e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"simbajigege","slug":"harness-step1-create-agent-md","github":{"repo":"simbajigege/book2skills","stars":36,"topics":["agent-skills","agentskills","anthropic","anthropic-claude","book2skills","growth-investing","investing","investing-skills","skills","stock-analysis"],"license":"mit","html_url":"https://github.com/simbajigege/book2skills","pushed_at":"2026-04-30T05:08:07Z","description":"Create best skills based on best books","skill_md_sha":"e3056c3e0bf84be3bf6ba13cd5c9d071b4823624","skill_md_path":"skills/harness-step1-create-agent-md/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/simbajigege/book2skills/tree/main/skills/harness-step1-create-agent-md"},"layout":"multi","source":"github","category":"book2skills","frontmatter":{"name":"harness-step1-create-agents-md","description":"Harness Engineering 第一阶段：扫描现有项目，生成 AGENTS.md（目录文件）和完整的 docs/ 知识库结构。\n\n当用户想要\"为项目添加 agent 支持\"、\"让 AI 更好地理解我的项目\"、\"开始 harness engineering\"、\n\"创建 AGENTS.md\"、\"搭建 agent 文档结构\"、\"让 Claude Code 更好地工作\"时，立即使用此 skill。\n\n也适用于用户说\"帮我把项目文档整理好给 agent 用\"、\"我想开始用 AI agent 开发\"等场景。"},"skills_sh_url":"https://skills.sh/simbajigege/book2skills/harness-step1-create-agent-md"},"updatedAt":"2026-05-01T12:56:53.919Z"}}