Agent-Skills-for-Context-Engineering 项目开发方法论从任务-模型适配到多阶段 LLM 流水线的完整工程指南【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering导读本文以 project-development 技能 为核心系统讲解在 Agent-Skills-for-Context-Engineering 技能集合中如何以整个项目或多阶段流水线为工作单元做出正确的工程决策包括在写任何代码之前评估任务是否适合交给 LLM任务-模型适配、设计 acquire→prepare→process→parse→render 五阶段流水线、以文件系统作为状态机管理中间产物、设计可解析的结构化输出、估算 Token 与美元成本、以及判断单代理与多代理的取舍。读完本文你将掌握一套可直接落地的 LLM 项目规划模板并能配合仓库自带的 pipeline_template.py 可运行脚本快速搭建自己的批处理流水线。一、技能定位工作单元是整个项目project-development 技能拥有的是项目级决策是否该用 LLM 构建、流水线应该是什么形状、成本是多少、如何迭代。它的职责边界在 SKILL.md 中划分得非常清楚属于本技能任务-模型适配判断、多阶段批处理/Agent 流水线塑形、Token/成本/时间线估算、项目级的单代理 vs 多代理选型、Agent 辅助迭代的组织方式、跨阶段交接格式流水线契约的结构化输出设计不属于本技能路由到相邻技能单个工具的描述、schema、命名、响应格式、错误消息 → tool-design单条轨迹的 Token 效率战术掩码、分区、缓存→ context-optimizationAgent 拓扑层面的子代理拆分决策 → multi-agent-patterns自主控制回路锁定指标、新颖性闸门、人工审批边界→ harness-engineering。这种项目级 vs 工具级 vs 拓扑级 vs 回路级的职责切分是该技能集合得以规模化协作的关键每个技能只在被激活时加载且彼此不重叠。从 README.md 的描述看project-development 属于开发方法论Development Methodology类技能与架构类multi-agent-patterns、tool-design、运营类evaluation、context-optimization技能互补。二、第一步永远先做任务-模型适配Task-Model Fit核心主张在写任何代码之前评估任务-模型适配度因为把自动化构建在一个根本不适配的任务上会浪费数天精力。原文档给出两张决策表这里完整展开。2.1 可以推进的任务特征Proceed特征理由跨来源综合Synthesis across sourcesLLM 比基于规则的替代方案更擅长合并多个输入的信息带评分标准的主观判断Subjective judgment with rubrics评分、评估、带准则的分类天然映射到语言推理自然语言输出Natural language output当目标是人类可读文本时LLM 原生就能产出错误容忍Error tolerance单点失败不会击垮整个系统LLM 的非确定性可以接受批处理Batch processing条目之间无需对话状态保持上下文干净训练数据中的领域知识Domain knowledge in training模型已具备相关背景降低提示工程开销2.2 应当停止的任务特征Stop特征理由精确计算Precise computation数学、计数、精确算法在语言模型中不可靠实时性要求Real-time requirementsLLM 延迟对亚秒级响应太高完美准确率要求Perfect accuracy requirements幻觉风险使 100% 准确率不可能实现专有数据依赖Proprietary data dependence模型缺乏必要上下文且无法仅靠提示获取顺序依赖Sequential dependencies每一步高度依赖上一步结果错误被级联放大确定性输出要求Deterministic output requirements相同输入必须产生相同输出LLM 无法保证仓库佐证这一判断方法不是空谈。在 researcher/claims/index.jsonl 中有一条以本技能为 owning_skill 的 claim 记录claim-project-development-vercel-d0-reduction其 claim_text 为Vercels d0 case study shows architectural reduction can improve agent success, latency, token usage, and step count when the underlying data layer is well documented.——可见这些方法论在仓库的研究循环中被当作可被验证、可被引用的论断来维护。三、手动原型验证Manual Prototype几分钟避免数小时返工在投入自动化之前总是先用人工方式验证任务-模型适配复制一条有代表性的输入到模型界面评估输出质量并回答四个问题模型是否具备完成该任务所需的知识模型能否按所需格式产出输出规模化之后应该期待什么级别的质量是否存在需要处理的明显失败模式为什么必须这么做因为失败的人工原型预示着失败的自动化系统而成功的人工原型既提供了质量基线又提供了提示设计模板。这个测试只需几分钟却能避免数小时的无效开发。Karpathy 的 HN Time Capsule 案例下文详述正是靠复制粘贴一篇文章评论线程到 ChatGPT这 5 分钟验证确认了模型能产出洞见分析、格式符合预期后才进入自动化构建的。四、流水线架构acquire → prepare → process → parse → renderLLM 项目应组织为分阶段流水线因为将确定性阶段与非确定性阶段分离可以快速迭代并控制成本。每个阶段应满足四个性质离散Discrete阶段之间边界清晰每个阶段可独立调试幂等Idempotent重跑产生相同结果避免重复工作可缓存Cacheable中间结果持久化到磁盘避免昂贵的重复计算独立Independent每阶段可单独运行支持选择性重执行。4.1 五阶段规范结构acquire - prepare - process - parse - render阶段职责确定性成本1. Acquire从数据源API、文件、数据库获取原始数据确定低2. Prepare将数据转换为提示格式确定低3. Process执行 LLM 调用昂贵、非确定步骤非确定高4. Parse从 LLM 输出中提取结构化数据确定低5. Render生成最终输出报告、文件、可视化确定低维持这种分离的核心价值只有 Stage 3 涉及 LLM 调用。当解析和渲染需要迭代时不必重跑昂贵的 LLM 阶段当 LLM 阶段需要重跑时也只针对必要条目。参考 pipeline-patterns.md 中的阶段特征表可知Acquire/Prepare/Parse 全部是确定性、低成本、可并行、幂等Process 是非确定、高成本、可并行、可缓存Render 则是部分可并行。4.2 仓库中的可运行模板pipeline_template.py本仓库的 project-development 技能附带了完整的 Python 模板脚本将上述五阶段落成了可运行的代码其 CLI 用法为python pipeline_template.py acquire --batch-id 2025-01-15 python pipeline_template.py prepare --batch-id 2025-01-15 python pipeline_template.py process --batch-id 2025-01-15 --workers 10 python pipeline_template.py parse --batch-id 2025-01-15 python pipeline_template.py render --batch-id 2025-01-15 python pipeline_template.py all --batch-id 2025-01-15 python pipeline_template.py clean --batch-id 2025-01-15 --clean-stage process python pipeline_template.py estimate --batch-id 2025-01-15CLI 参数见 pipeline_template.py 的 main 函数包括参数默认值说明stage位置参数必填可选acquire/prepare/process/parse/render/all/clean/estimate--batch-id当天日期批次标识符--limitNone限制条目数用于测试--workers5Process 阶段并行 worker 数--modelclaude-sonnet-4-20250514处理所用模型--clean-stageNoneclean时仅清理该阶段及其下游各阶段函数stage_acquire/stage_prepare/stage_process/stage_parse/stage_render/stage_clean/stage_estimate均已在 pipeline_template.py 中实现并留有明确的# CUSTOMIZE注释位数据获取fetch_items_from_source、LLM 调用call_llm、渲染逻辑render_html。Process 阶段使用ThreadPoolExecutor并行提交 LLM 调用并对每个条目将响应写入response.md作为缓存。模板同时支持编程式调用例如from pipeline_template import stage_acquire, stage_prepare, stage_process stage_acquire(2025-01-15, limit5) stage_prepare(2025-01-15) stage_process(2025-01-15, modelclaude-sonnet-4-20250514, max_workers3)五、文件系统即状态机File System as State Machine用文件系统而非数据库或内存结构来追踪流水线状态因为文件的存在性天然提供幂等性并且可读、可调试。每个条目在磁盘上拥有一个目录各阶段的输出文件即状态标记data/{id}/ raw.json # acquire 阶段完成 prompt.md # prepare 阶段完成 response.md # process 阶段完成 parsed.json # parse 阶段完成工作方式极其简单判断是否需要处理检查输出文件是否存在。needs_processing(item_dir, stage)模式在 pipeline-patterns.md 中有完整实现重跑某个阶段删除该阶段的输出文件及其下游文件。clean_from_stage按[acquire, prepare, process, parse, render]的阶段顺序从指定阶段起逐级清理模板中的stage_clean亦实现了同样的语义调试直接读取中间文件。该模式之所以成立是因为每个目录彼此独立从而支持简单并行化与廉价的缓存。参考 pipeline-patterns.md 的目录结构扩展版project/ ├── data/ │ └── {batch_id}/ │ └── {item_id}/ │ ├── raw.json # Acquire 输出 │ ├── prompt.md # Prepare 输出 │ ├── response.md # Process 输出 │ └── parsed.json # Parse 输出 ├── output/ │ └── {batch_id}/ │ └── index.html # Render 输出 └── config/ └── prompts/ └── template.md # 提示模板在 examples/x-to-book-system/SKILLS-MAPPING.md 中可以看到这一思想在真实系统设计里的落地该 X-to-Book 系统所有 agent 间的数据流都经过文件系统阶段输出存盘而不是通过 Orchestrator 转述从而规避了 supervisor 模式中的传话游戏telephone game问题——这正与 project-development 的文件系统状态机主张相互印证。六、结构化输出设计让解析可靠提示设计直接决定解析可靠性。每一个结构化提示都应包含以下四类元素节标记Section markers显式的标题或前缀解析器可以据此匹配格式示例Format examples精确展示输出应该长什么样理由披露Rationale disclosure写明我将程序化解析这段输出让模型优先服从格式受约束的值Constrained values枚举选项、分数区间、固定格式。6.1 提示模板示范pipeline-patterns.md 给出了 INSTRUCTION / FORMAT SPECIFICATION / FORMAT ENFORCEMENT / CONTENT 四段的提示模板骨架pipeline_template.py 中的PROMPT_TEMPLATE则是可直接使用的实例Analyze the following content and provide your response in exactly this format. ## Summary [2-3 sentence summary of the content] ## Key Points - [Point 1] - [Point 2] - [Point 3] ## Score Rating: [1-10] Confidence: [low/medium/high] ## Reasoning [Explanation of your analysis] Follow this format exactly because I will be parsing it programmatically. --- # Content to Analyze Title: {title} {content}HN Time Capsule 案例中的 6 节输出提示摘要 → 事实走向 → 最有先见之明/最离谱评论颁奖 → 其他亮点 → 逐人评分 → 0-10 总分是同一套原则的完整体现其第 6 节的Final grades标题 name: grade (optional comment) 无序列表格式配合Please follow the format exactly because I will be parsing it programmatically这句理由披露构成了可解析契约。6.2 解析器必须优雅容忍变化LLM 不可能完美遵循指令因此要构建宽容的解析器。仓库提供了四个基础解析原语见 pipeline_template.pypipeline-patterns.md 中有完整实现extract_section(text, section_name)用正则(?:^|\n)(?:# *)?{section_name}[:\s]*\n(.*?)(?\n#|\Z)按节标题抽取内容兼容可选 Markdown 标题符extract_field(text, field_name)抽取Field: value、Field - value、**Field**: value形式的键值对extract_list_items(text, section_name)从节内抽取-/*开头的列表项extract_score(text, field_name, min_val, max_val)抽取数字分数并用max(min_val, min(max_val, score))夹紧到合法区间。关键实践正则要足够灵活以容忍细微格式变化节缺失时提供合理默认值解析失败要记录日志供人工复查而不是崩溃。ParsedResult数据结构携带parse_errors: list[str]字段parse_response对每个字段单独 try/except任何字段失败都会追加到parse_errors并继续解析其余字段——这就是优雅降级的具体实现。HN 案例的parse_grades正则会同时匹配 ASCII 减号和 Unicode 减号[\-−]?即宽容解析的实战示例。七、Agent 辅助开发以迭代换速度使用具备 Agent 能力的模型加速开发描述项目目标与约束 → 让 Agent 生成初始实现 → 针对具体失败进行测试与迭代 → 根据结果精化提示与架构。保持输出聚焦与高质量的四条实践前期给出清晰、具体的要求减少返工轮次将大项目拆分为离散组件使每个组件可独立验证在进入下一组件之前测试当前组件尽早暴露失败让 Agent 一次只专注一个任务防止上下文退化。八、成本与规模估算公式 模板 运行时追踪在开工前估算 LLM 处理成本因为 Token 成本在规模化时会迅速累积预算超支的晚期发现会迫使代价高昂的重构。核心公式Total cost (items x tokens_per_item x price_per_token) API overhead对于批处理估算每条目的输入 Token提示上下文、输出 Token典型响应长度乘以条目数再额外加上20%-30% 的缓冲用于重试与失败。pipeline-patterns.md 给出了配套代码基于tiktoken的count_tokens与estimate_cost按(tokens/1_000_000) * price_per_mtok分别计算输入/输出成本以及按批次汇总的estimate_batch_cost返回条目数、总输入/输出 Token、预估美元成本、每条目平均成本。pipeline_template.py 中的stage_estimate则以--dry-run等价的方式实现按1 Token ≈ 4 字符粗略估算输入 Token、每响应 500 Token 估算输出并用示例定价输入 $3/MTok、输出 $15/MTok打印成本预估同时注明实际成本可能不同建议预留 20-30% 缓冲。开发期间持续追踪实际成本。若成本显著超估可截断以减少上下文长度对简单条目改用更小模型缓存并复用部分结果增加并行处理以缩短墙钟时间。九、单代理 vs 多代理默认简单按需升级批处理且条目独立的场景默认使用单代理流水线因为它更易管理、更便宜、更易调试。仅当满足以下任一条件时升级为多代理需要对不同方面进行并行探索任务超出单个上下文窗口容量专门子代理在基准上被证明能切实提升质量。关键原则选择多代理是为了上下文隔离而不是角色拟人化。子代理获得全新的上下文窗口专注于子任务从而防止长时间任务中的上下文退化。架构细节路由到 multi-agent-patterns。从 examples/x-to-book-system/SKILLS-MAPPING.md 可见该取舍的真实应用X-to-Book 系统选择了 Supervisor/Orchestrator 模式理由是图书生产有清晰的顺序阶段抓取→分析→综合→写作→编辑阶段间的质量闸门需要中心协调。同时它也贯彻了上下文隔离原则——每个 agent 在其阶段拥有干净上下文Orchestrator 仅做路由、50k 上下文不接收原始数据阶段输出通过文件系统流转。十、架构简化Architectural Reduction减法优于加法从最小架构开始仅在生产证据证明必要时增加复杂度因为过度工程的脚手架常常限制而非释放模型性能。两个典型案例Vercel d0将 17 个专用工具缩减为两个原语命令执行 SQL后成功率与执行速度均提升claim 编号claim-project-development-vercel-d0-reduction详见 case-studies.md 与 docs/vercel_tool.md文件系统 Agent 模式使用标准 Unix 工具grep、cat、find、ls而非定制探索工具。10.1 何时缩减 / 何时增加缩减Reduce when数据层文档完善且结构一致模型推理能力足够专用工具在约束而非释放模型维护脚手架的时间超过改进产出的时间。增加Add complexity when底层数据混乱、不一致或文档缺失领域需要模型不具备的专门知识安全约束要求限制 Agent 能力操作确实复杂能从结构化流程中受益。工具级细节路由到 tool-design其中合并原则与本节的缩减主张一脉相承。十一、迭代与重构为变化而构建从一开始就为多次架构迭代做规划因为规模化生产 Agent 系统必然需要重构。仓库案例记录了两条佐证Manus 自发布以来已五次重构其 Agent 框架Bitter Lesson苦涩的教训提示我们——为当前模型局限而添加的结构会随着模型变强而变成约束。遵循三条实践保持架构简单、不固执己见使重构代价低廉跨模型代际测试验证 harness 没有限制性能设计能从模型进步中受益的系统而不是锁定当前局限。十二、项目规划模板五步走按顺序执行以下五步因为每一步都在下一步投入精力之前验证假设任务分析Task Analysis显式定义输入与期望输出分类综合、生成、分类还是分析基于业务影响设定可接受的错误率估算每次成功完成的价值以论证成本。人工验证Manual Validation用目标模型测试一个代表性示例对照需求评估输出质量与格式识别需要解析器加固或提示修订的失败模式估算每条目 Token 以用于成本预测。架构选择Architecture Selection依据上述标准选择单流水线 vs 多代理确定所需工具与数据源用文件系统状态设计存储与缓存策略为 Process 阶段规划并行化方案。成本估算Cost Estimation以 20%-30% 缓冲计算 items × tokens × price估算每个流水线阶段的开发时间确定基础设施需求API 密钥、存储、算力预估生产运行的持续运营成本。开发计划Development Plan逐阶段实现每阶段先测试再继续为每阶段定义含期望输出的测试策略设定与质量指标挂钩的迭代里程碑规划带回滚能力的部署方案。十三、典型案例深度拆解13.1 案例一批量分析流水线Karpathy 的 HN Time Capsule任务用事后诸葛亮的视角分析 10 年前的 930 篇 Hacker News 讨论并给评论者打分。架构详见 case-studies.md5 阶段流水线fetch → prompt → analyze → parse → render文件系统状态data/{date}/{item_id}/下存放各阶段输出文件meta.json、article.txt、comments.json、prompt.md、response.md、grades.json、score.json结构化输出6 节 明确格式要求Final grades标题、字母评分、0-10 总分并行执行15 个 worker 的ThreadPoolExecutor并发调用 LLM。实测结果总成本约$58执行约1 小时产出静态 HTML逐日页面 Hall of Fame 聚合排行。该案例验证了方法论中的五个要点人工验证先行、文件系统即状态、幂等阶段重跑只处理缺输出文件的条目、Agent 辅助实现约 3 小时从需求到可运行代码、并行执行在不增加 Token 成本的前提下缩短墙钟时间。13.2 案例二架构简化Vercel d0任务构建文本转 SQL Agent让全员通过 Slack 用自然语言查询分析数据。初始方案是 17 个专用工具 重度提示工程约束 手工检索 schema结果80% 成功率、平均 274.8 秒执行、约 102k Token、约 12 步且维护负担持续。核心问题在于团队在替模型解决它本可自行处理的问题预过滤上下文、约束选项、给每次交互包上验证逻辑、保护模型免受复杂性伤害。重构后仅保留两个工具ExecuteCommand ExecuteSQL 沙箱直接文件系统访问 以 YAML/Markdown/JSON 承载的语义层。结果对比case-studies.md 记录平均执行时间 274.8s → 77.4s快 3.5 倍、成功率 80% → 100%、平均 Token 约 102k → 约 61k少 37%、平均步数约 12 → 约 7少 42%。最差案例从 724 秒/100 步/145k Token 且失败降为同一查询 141 秒/19 步/67k Token 且成功。成功原因语义层本身就是良好的文档Claude 只需要直接读取文件的权利文件系统是模型在训练中已深度理解、经数十年验证的抽象当模型变强后护栏从助力变成了阻力。这正是 researcher/claims/index.jsonl 中记录的那条 claim 的实证来源。13.3 跨案例共性模式成功因素①自动化前先人工验证②文件系统作为地基Karpathy 用于状态、Vercel 用于工具接口③架构简化优于复杂多个案例一致④结构化输出 宽容解析⑤为迭代做预期没有项目一次做对架构。 失败模式①过度约束模型护栏随能力提升变成负债②工具泛滥更多工具 更多混淆③隐藏错误从上下文移除失败会剥夺模型学习所需的证据④过早优化在基本功能可用前加复杂度⑤忽视经济性Token 成本快速累积。十四、十条准则Guidelines构建自动化之前先用人工原型验证任务-模型适配将流水线组织为离散、幂等、可缓存的阶段用文件系统进行状态管理与调试为结构化、可解析的输出设计提示并给出显式格式示例从最小架构开始仅在证有必要时增加复杂度尽早估算成本并在开发全程追踪构建能容忍 LLM 输出变化的健壮解析器预期并规划多次架构迭代测试脚手架是在帮助还是约束模型性能使用 Agent 辅助开发快速迭代实现。十五、九个常见陷阱Gotchas跳过人工验证在验证模型能胜任任务之前就构建自动化在方案根本性错误时会浪费大量时间。务必先把一个代表性示例跑过模型界面。单体流水线把全部阶段揉进一个脚本会让调试和迭代寸步难行。用持久化中间输出分离阶段使每阶段可独立重跑。过度约束模型加护栏、预过滤、验证逻辑——若这些模型本可自行处理反而会降低性能。保留前先测试其利弊。上线前忽视成本Token 成本规模化后快速累积。从第一天就估算并追踪避免预算意外迫使架构返工。追求完美解析期待 LLM 完美遵循格式指令会造就脆弱系统。构建能容忍变化并记录失败的健壮解析器。过早优化在基础流水线正确运行前就加缓存、并行与优化会把精力浪费在迭代中可能被丢弃的代码上。模型版本锁定构建只适配单一模型版本的流水线会造就脆弱系统。跨模型代际测试抽象 LLM 调用层使模型可替换而无需重写流水线逻辑。无评估就上线不度量输出质量就发布 Agent 流水线回归将无法被发现。开发期就定义质量指标并在每次模型/提示变更前后运行评估检查。来源漂移Provenance drift原始输入、中间输出、最终提案散落在临时文件夹中会变得无法审计。把每次流水线运行放进单一目录保留来源证据、转换过程、验证报告与决策记录。十六、技能集成项目级决策与相邻技能的边界project-development 拥有项目形状与流水线决策相邻决策归属如下SKILL.md 的 Integration 一节tool-design工具接口层描述、schema、响应格式、错误消息、MCP 命名空间、单个工具合并。问题若是这个具体工具应该长什么样而非流水线应该长什么样路由到此multi-agent-patternsAgent 拓扑supervisor vs swarm vs 层级、交接协议、跨 Agent 上下文隔离。本技能只在项目级选单/多拓扑细节归它harness-engineering项目外围的自主控制回路锁定指标、新颖性闸门、运行状态机、人工审批边界。问题若是如何让它无人值守跑数天路由到此context-fundamentals塑造每个阶段提示设计的上下文约束概念框架evaluation流水线运行的结果度量与质量闸门context-compression长流水线阶段产生需要摘要的轨迹时使用。examples/x-to-book-system/SKILLS-MAPPING.md 展示了这套集成如何形成合力多代理的上下文隔离 文件系统协调规避传话游戏 上下文预算分配 工具合并3 个合并工具替代 15 窄工具 加权多维评估矩阵构成了一个技能互补、协同工作的完整示例。十七、本文要点回顾项目级工程决策有明确的方法论顺序任务-模型适配 → 人工原型 → 架构选择 → 成本估算 → 分阶段实现流水线的经济性来自确定性/非确定性阶段分离只有 Process 阶段昂贵且非确定其余阶段均可独立调试与廉价重跑文件系统即状态机提供了幂等、可缓存、可并行三大工程红利结构化输出 宽容解析是LLM 非确定性与下游程序确定性之间的桥梁模板脚本与解析原语均可直接复用pipeline_template.py架构上默认最小化用生产证据而非预测来决定是否增加复杂度Vercel d0 与 HN Time Capsule 分别是减法与批处理范式两个方向的实证样本详见 case-studies.md 与 pipeline-patterns.md。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考