
Skill Name【免费下载链接】nangoBuild product integrations with AI.项目地址: https://gitcode.com/GitHub_Trending/na/nangoOverviewCore principle in 1-2 sentences. What is this?When to UseBullet list with symptoms and use casesWhen NOT to useQuick ReferenceTable or bullets for common operationsImplementationInline code for simple patterns Link to separate file for heavy reference (100 lines)Common MistakesWhat goes wrong how to fixReal-World Impact (optional)Concrete results from using this technique这个模板在仓库内被大量实践。例如 .agents/skills/running-tests/SKILL.md 依次包含 Overview、Quick Reference命令速查表、Running Specific Tests、Common Mistakes错误-症状-修复对照表.agents/skills/creating-integration-docs/SKILL.md 则包含 When to Use / When NOT to Use、Quick Reference、File Templates、Common Mistakes、Implementation Checklist。当你为 Nango 或任何项目新增技能时直接复用同一骨架即可保证一致性。 ## Degrees of Freedom自由度匹配原则 **技能的具体程度要与任务的复杂度相匹配** - **高自由度任务需要判断力的灵活任务**使用宽泛的指导、原则与示例让 Agent 结合上下文自行调整。例如Use when designing APIs - provides REST principles and patterns。 - **低自由度任务脆弱或关键的操作**必须给出精确步骤与校验点。例如Use when deploying to production - follow exact deployment checklist with rollback procedures。 **红旗信号** - 若技能在创意型任务上过度约束 Agent应降低具体程度 - 若技能在关键操作上过于含糊则应补充明确步骤。 仓库中的对比很典型adding-audit-events 属于低自由度场景审计事件涉及词汇表、中间件挂载顺序、webapp 常量表等多处联动因此它的正文用 9 步 Workflow 加 Review Checklist 精确规定每一步该改哪个文件而 creating-skills-skill 本身属于高自由度场景写作风格因任务而异因此以原则和模式为主留出适应空间。 ## Skill Discovery Optimization可发现性优化 **关键认知Agent 通常只凭 description 判断技能是否相关因此必须为被发现而优化。** 一个描述模糊的技能写得再好也不会被调用。 ### description 最佳实践 yaml # ❌ BAD - Too vague, doesnt mention when to use description: For async testing # ❌ BAD - First person in agent-facing metadata description: I help you with flaky tests # ✅ GOOD - Triggers what it does description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests # ✅ GOOD - Technology-specific with explicit trigger description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management仓库实例验证了这套写法.agents/skills/ui-visual-debugging/SKILL.md的 description 同时给出了触发条件Use when modifying or visually debugging Nango frontend UI、覆盖范围webapp、connect-ui、browser interactions、screenshots、visual regressions以及方法偏好优先 PlaywrightPeekaboo 仅限特定场景。关键词覆盖描述中要使用 Agent 可能用来匹配的词汇错误消息ENOENT、Cannot read property、Timeout症状flaky、hanging、race condition、memory leak同义词cleanup/teardown/afterEach、timeout/hang/freeze工具名真实命令名、库名、文件类型。命名规范使用动名词形式✅creating-skills而不是skill-creation✅testing-with-subagents而不是subagent-testing✅debugging-memory-leaks而不是memory-leak-debugging✅processing-pdfs而不是pdf-processor✅analyzing-spreadsheets而不是spreadsheet-analysis为什么动名词有效它描述的是你正在采取的行动主动、清晰、一致、面向行动。避免❌ 含糊的名字如 Helper、Utils❌ 被动语态结构。Nango 仓库 .agents/skills 目录下的全部技能都遵循了这一约定running-tests、building-and-verifying、creating-database-migrations、creating-integration-docs、running-and-testing-locally、adding-audit-events、ui-visual-debugging——全部是动词 -ing 的动名词形式。Code Examples代码示例规范一个优秀的示例胜过许多平庸的示例。按场景选择语言测试技巧 → TypeScript/JavaScript系统调试 → Shell/Python数据处理 → PythonAPI 调用 → TypeScript/JavaScript优秀示例清单完整且可运行注释解释WHY为什么而不只是 what做了什么来自真实场景而非虚构清晰展示模式可直接改造适配而非通用模板同时展示 BAD❌与 GOOD✅两种写法包含真实的上下文/环境准备代码示例模板// ✅ GOOD - Clear, complete, ready to adapt interface RetryOptions { maxAttempts: number; delayMs: number; backoff?: linear | exponential; } async function retryOperationT( operation: () PromiseT, options: RetryOptions ): PromiseT { const { maxAttempts, delayMs, backoff linear } options; for (let attempt 1; attempt maxAttempts; attempt) { try { return await operation(); } catch (error) { if (attempt maxAttempts) throw error; const delay backoff exponential ? delayMs * Math.pow(2, attempt - 1) : delayMs * attempt; await new Promise(resolve setTimeout(resolve, delay)); } } throw new Error(Unreachable); } // Usage const data await retryOperation( () fetchUserData(userId), { maxAttempts: 3, delayMs: 1000, backoff: exponential } );不要这样做❌ 用 5 种语言重复实现移植是你的强项不需要示例代劳❌ 制造填空题式的模板❌ 编写虚构场景的示例❌ 只贴代码不加注释。File Organization文件组织方式自包含首选typescript-type-safety/ SKILL.md # Everything inline适用场景全部内容约 500 词以内即可容纳无需重型参考。带支持文件api-integration/ SKILL.md # Overview patterns retry-helpers.ts # Reusable code examples/ auth-example.ts pagination-example.ts适用场景需要可复用工具或多个完整示例。带重型参考aws-sdk/ SKILL.md # Overview workflows s3-api.md # 600 lines API reference lambda-api.md # 500 lines API reference适用场景参考资料超过 100 行。仓库中的 agent-builder-skill 正是带支持文件的实例SKILL.md承载完整方法论旁边的EXAMPLES.md则单独存放可落地的完整子代理实现避免主文件被示例撑爆。Token EfficiencyToken 效率控制Skill 会加载进每一次对话因此必须保持精简。这是 Skill 设计中最容易被忽视、却直接影响所有会话开销的约束。目标限制SKILL.md控制在 500 行以内上手流程getting-started workflows少于 150 词高频加载的技能总计少于 200 词其他技能少于 500 词。对每条信息都问一句Agent 真的需要这段解释吗不需要就删。压缩技巧# ❌ BAD - Verbose (42 words) Your human partner asks: How did we handle authentication errors in React Router before? You should respond: Ill search past conversations for React Router authentication patterns. Then dispatch a subagent with the search query: React Router authentication error handling 401 # ✅ GOOD - Concise (20 words) Partner: How did we handle auth errors in React Router? You: Searching... [Dispatch subagent → synthesis]技术手段引用工具--help的输出而不是在文档里罗列全部 flag交叉引用其他技能而不是重复内容只展示模式的最小示例消除冗余使用渐进式披露progressive disclosure按需引用额外文件而不是一次性全量加载按领域组织内容让上下文更聚焦。Workflow Recommendations多步骤流程的写法对于多步骤过程技能中应包含清晰的顺序步骤把复杂任务拆成带编号的操作反馈回路内置验证/校验步骤错误处理说明出错时该检查什么清单用于步骤多、细节易遗漏的过程。推荐结构## Workflow 1. **Preparation** - Check prerequisites - Validate environment 2. **Execution** - Step 1: [action expected result] - Step 2: [action expected result] 3. **Verification** - [ ] Check 1 passes - [ ] Check 2 passes 4. **Rollback** (if needed) - Steps to undo changes仓库内的 creating-database-migrations/SKILL.md 是紧凑工作流的范例5 步流程确定迁移目录 → 阅读近期迁移学习风格 → 按时间戳格式命名 → 决定exports.down→ 选择外键删除行为之后紧跟一个 Review Checklist把容易遗漏的细节全部固化为勾选项。Common Mistakes常见错误速查MistakeWhy It FailsFixNarrative exampleIn session 2025-10-03...Focus on reusable patternMulti-language dilutionSame example in 5 languagesOne excellent exampleCode in flowchartsstep1 [labelimport fs]Use markdown code blocksGeneric labelshelper1, helper2, step3Use semantic namesMissing description triggersFor testingUse when tests are flaky...First-person descriptionI help you...Use when... - provides...Deeply nested file referencesMultiple symbols, complex pathsKeep references simple and directWindows-style file pathsC:\path\to\fileUse forward slashesOffering too many options10 different approachesFocus on one proven approachPunting error handlingThe agent figures it outInclude explicit error handling in scriptsTime-sensitive informationAs of 2025...Keep content evergreenInconsistent terminologyMixing synonyms randomlyUse consistent terms throughout这条表本身也是技能写作的示范错误 → 失败原因 → 修复方式三列Agent 可以在几秒内完成对照排查。Flowchart Usage流程图的使用边界只在以下场景使用流程图不显而易见的决策点可能过早停止的流程循环何时用 A 而非 B的抉择。永远不要用于参考资料 → 用表格/列表代码示例 → 用 Markdown 代码块线性指令 → 用编号列表。一句话流程图服务于决策不服务于陈述。Cross-Referencing Skills技能间交叉引用# ✅ GOOD - Name only with clear requirement **REQUIRED:** Use superpowers:test-driven-development before proceeding **RECOMMENDED:** See typescript-type-safety for proper type guards # ❌ BAD - Unclear if required See skills/testing/test-driven-development # ❌ BAD - Force-loads file, wastes context skills/testing/test-driven-development/SKILL.md交叉引用遵循三条原则只写技能名不写文件路径、明确标注 REQUIRED / RECOMMENDED 以区分必要性与建议性、绝不通过 强制加载文件那会白白浪费上下文窗口。Nango 仓库内部已经实践了这套交叉引用.agents/skills/ui-visual-debugging/SKILL.md明确指出 For local startup details, userunning-and-testing-locallyas the source of truth而 AGENTS.md 也指向 use therunning-and-testing-locallyskill 获取完整的本地开发说明——通过技能名而不是路径来引用即使文件位置变动引用依然有效。Advanced Practices进阶实践迭代开发最佳方式与 Agent 一起迭代开发技能。从最小可用版本起步用真实用例测试根据实际效果持续打磨删掉没有带来价值的段落。先建评估再写文档在投入大量文档工作之前先创建测试场景明确什么算做得好记录被验证的模式跳过纯理论性的改进。工具脚本为保证可靠性脚本应提供显式的错误处理成功/失败的退出码清晰的错误消息用法示例。#!/bin/bash set -e # Exit on error if [ ! -f config.json ]; then echo Error: config.json not found 2 exit 1 fi # Script logic here echo Success exit 0结构化输出的模板当技能需要产出固定格式时## Output Template typescript interface ExpectedOutput { status: success | error; data: YourDataType; errors?: string[]; }Usage: Copy and adapt for your context## Skill Creation Checklist创建清单 **写之前** - [ ] 该技术点并不显而易见或没有在别处被充分记录 - [ ] 模式可广泛复用非项目专属 - [ ] 我以后会在多个项目中引用它 **Frontmatter** - [ ] 名称只含字母、数字、连字符 - [ ] 描述以 Use when... 开头 - [ ] 描述同时包含触发条件与技能作用 - [ ] 描述使用第三人称 - [ ] Frontmatter 总长小于 1024 字符 **内容** - [ ] Overview 陈述核心原则1-2 句 - [ ] When to Use 一节列出症状 - [ ] 常见操作的 Quick Reference 表格 - [ ] 一个优秀代码示例针对技巧型技能 - [ ] Common mistakes 一节 - [ ] 全文分布可检索的关键词 **质量** - [ ] 词数与使用频率匹配见上文目标 - [ ] SKILL.md 在 500 行以内 - [ ] 无叙事性故事 - [ ] 流程图仅用于非显而易见决策 - [ ] 支持文件仅在必要时引入100 行参考 - [ ] 交叉引用使用技能名而非文件路径 - [ ] 不含时效性信息 - [ ] 全文术语一致 - [ ] 具体示例而非模板 - [ ] 自由度与任务复杂度匹配 **测试针对纪律约束型技能** - [ ] 已用子代理场景测试 - [ ] 覆盖常见合理化借口 - [ ] 包含红旗信号清单 ## Directory Structure目录与扁平命名空间skills/ skill-name/ SKILL.md # Required supporting-file.* # Optional examples/ # Optional example1.ts scripts/ # Optional helper.py【免费下载链接】nangoBuild product integrations with AI.项目地址: https://gitcode.com/GitHub_Trending/na/nango创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考