30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度如果你在2025年或2026年才开始关注AI Agent并且想从零开始学习如何开发一个真正能用的Agent Skill那么你很可能已经错过了最直观的入门窗口。现在你面对的不是一个清晰的学习路径而是一片由“框架”、“工具链”、“最佳实践”和“生态”构成的、令人眼花缭乱的术语丛林。你可能会看到无数教程告诉你“安装这个插件”、“使用那个命令”但很少有人告诉你为什么一个简单的“技能”需要如此复杂的结构以及从“跑通一个例子”到“开发一个能稳定工作的技能”之间到底隔着多少看不见的坑。这篇文章不会重复那些随处可见的安装命令列表。我想和你探讨的是在Agent Skill这个看似简单的概念背后隐藏着一种全新的、关于如何“教会”AI去完成特定任务的工程化思维。这种思维才是决定你能否从“会用”走向“会造”的关键。我们将从最根本的问题开始一个Skill到底是什么它为什么能工作然后我们会一步步拆解如何从零开始把一个模糊的想法变成一个结构清晰、可复用、甚至能分享给他人的标准化Skill。最后我们会深入到代码层面看看一个Skill的“骨架”和“血肉”究竟是如何构成的。1. 重新理解“Skill”它不只是个文件夹而是一套可复用的“工作记忆”很多人第一次接触Skill会把它理解成一个“插件”或“脚本包”。这个理解没错但太浅了。让我们换个角度Skill的本质是一套被结构化封装起来的“工作记忆”和“操作流程”。想象一下你每次让AI帮你写周报都需要重新解释一遍公司背景、你的岗位、本周重点、汇报对象、喜欢的格式……这是低效的重复。而一个“周报生成Skill”就是把所有这些背景信息、模板、写作要点打包成一个标准化的“知识包”。当你启用这个Skill时AI不是从零开始思考而是直接加载了这套预设的“工作记忆”瞬间进入“周报专家”的角色。这就是Skill与普通Prompt最核心的区别普通Prompt每次对话都是一次性的上下文。任务结束记忆清零。Skill将成功的任务经验背景、步骤、模板、规则沉淀为可复用的资产。下次需要时直接“调用”这套经验。所以当你看到Skill的标准目录结构时就能理解每个文件的作用了my-weekly-report-skill/ ├── SKILL.md # 核心定义这个Skill是什么、怎么用、输入输出是什么AI的“任务说明书” ├── references/ # 背景资料公司介绍、数据字典、行业术语AI的“参考资料库” ├── scripts/ # 可执行脚本数据获取、格式转换、调用APIAI的“自动化工具” └── assets/ # 静态资源报告模板、Logo图片、样式文件AI的“素材库”这个结构不是为了好看而是为了让AI能够按需、渐进式地加载和理解一个复杂任务。SKILL.md是总纲告诉AI任务目标当任务深入时AI可以根据需要去references/里查找细节或执行scripts/里的脚本来获取数据。1.1 为什么“结构化”如此重要你可能会问我把所有东西都写在一个巨大的Prompt里不行吗理论上可以但会立刻遇到两个天花板上下文长度限制再大的模型其上下文窗口也是有限的。一个包含数十个模板、大量背景知识的巨型Prompt会迅速耗尽宝贵的Token导致AI无法有效处理你的核心指令。认知负荷过载一次性给AI灌输所有信息就像给一个新员工第一天就扔给他一整本员工手册。他无法有效吸收和索引。结构化的好处在于按需加载AI只在需要用到某个部分时才去“翻阅”对应的文件这使得它的“思考”更聚焦、更高效。因此学习开发Skill的第一个思维转变就是从编写单次对话的Prompt转变为设计一套可被AI理解和执行的“程序化工作流”。1.2 Skill的两种核心范式“知识库型”与“工具调用型”根据Skill主要解决的问题我们可以将其分为两大类这决定了你的开发重心技能类型核心价值典型文件开发重点知识库型让AI掌握某个垂直领域的专业知识或公司内部信息。SKILL.md,references/信息的结构化整理、术语解释、案例库构建、检索逻辑设计。工具调用型赋予AI操作外部系统、处理数据或执行自动化任务的能力。SKILL.md,scripts/脚本的健壮性、错误处理、输入输出规范、API安全封装。当然很多优秀的Skill是两者的结合。例如一个“竞品分析Skill”既需要references/里存放市场报告和产品文档知识库也需要scripts/里的脚本来爬取最新的官网信息或应用商店评论工具调用。理解这个分类能帮助你在动手前就想清楚我这个Skill到底要解决哪一类问题我的主要精力应该放在整理资料上还是编写可靠的脚本上2. 从想法到蓝图如何系统化地设计你的第一个Skill不要一上来就打开编辑器写SKILL.md。那大概率会写出一个混乱、边界模糊、难以使用的Skill。正确的起点是进行任务拆解与蓝图设计。2.1 第一步用“用户故事”定义清晰边界问自己几个问题谁会用这个Skill开发者、运营、设计师在什么场景下用写代码时、做周报时、分析数据时用户的核心目标是什么用一句话描述例如“快速生成符合公司规范的API接口文档”完成这个目标需要哪些输入接口定义JSON功能描述文字成功的输出是什么一个格式良好的Markdown文档一个包含示例的Swagger文件把这些答案写下来就是一个最简单的“用户故事”。它能帮你牢牢锁定Skill的核心功能避免陷入“什么功能都想加”的陷阱。2.2 第二步拆解任务流程划分“人机协作”边界接下来把用户目标拆解成具体的步骤。关键是要想清楚哪些步骤AI擅长理解、生成、规划哪些步骤需要外部工具或人工干预获取实时数据、执行系统命令、人工审核。以“生成API文档”为例输入解析AI擅长。理解用户提供的接口描述或代码片段。信息补全AI擅长。根据惯例补全可能的请求头、状态码说明、错误示例。模板填充AI擅长。将结构化信息填入预设的Markdown模板。实时数据获取AI不擅长。如果需要从线上Swagger服务器拉取最新定义就需要一个scripts/fetch_swagger.py。格式校验与发布可能混合。AI可以校验基本格式但发布到Confluence或生成PDF可能需要另一个脚本。这个拆解过程直接决定了你的Skill目录里需要哪些文件。步骤1-3主要靠SKILL.md中的指令和assets/template.md步骤4需要一个脚本步骤5可能还需要一个脚本或明确的后续手动步骤说明。2.3 第三步设计SKILL.md——AI的“任务手册”SKILL.md是Skill的灵魂。它不应该是一堆命令的堆砌而应该像一份优秀的项目说明书或操作手册。一个结构清晰的SKILL.md通常包含以下部分# Skill名称API文档生成助手 ## 技能描述 本技能用于帮助开发者快速生成标准、易读的API接口文档。它能够解析接口定义自动补全常见字段并套用可定制的模板输出Markdown格式文档。 ## 核心能力 - 解析自然语言描述的接口功能生成结构化定义。 - 支持从代码片段如Python Flask装饰器中提取接口信息。 - 提供多种文档模板基础版、详细版、团队内部版。 - 可选的Swagger JSON同步功能需配置。 ## 如何使用 1. **激活技能**在对话中提及“生成API文档”或直接使用本技能。 2. **提供输入**你可以 - 直接描述接口如“需要一个用户登录的POST接口路径是/auth/login接收用户名和密码。” - 粘贴代码片段。 - 提供一个现有的Swagger JSON路径需要提前运行同步脚本。 3. **交互与调整**我会根据你的输入生成草案你可以要求我调整任何部分。 4. **获取输出**最终文档将以Markdown格式提供你可以直接复制使用。 ## 文件与资源说明 - references/api_guidelines.md本团队内部的API设计规范生成文档时会参考此规范。 - assets/template_basic.md基础文档模板。 - assets/template_detailed.md包含更多示例和说明的详细模板。 - scripts/sync_from_swagger.py从远程Swagger URL拉取最新定义的脚本。**使用前需要配置目标URL**。 ## 注意事项 - 生成的文档需人工复核业务逻辑准确性。 - 同步脚本需要网络权限且仅支持标准的Swagger 2.0/OpenAPI 3.0格式。 - 技能不存储任何输入的接口数据。这份“手册”明确了技能的目的、用法、边界和依赖让AI和用户都能清晰理解如何协作。3. 实战开发构建一个“代码审查助手”Skill让我们通过一个相对复杂的例子——“代码审查助手”将上述设计理念付诸实践。这个Skill的目标是帮助开发者在提交代码前快速进行一轮基于最佳实践的自动化审查。3.1 项目初始化与结构搭建首先创建标准的Skill目录结构mkdir code-review-assistant cd code-review-assistant mkdir -p references scripts assets touch SKILL.md3.2 编写核心SKILL.md这是最关键的部分它定义了整个Skill的行为逻辑。# Skill名称智能代码审查助手 ## 技能描述 我是一个专注于代码质量审查的助手。我的目标是帮助你提前发现代码中可能存在的缺陷、坏味道、安全漏洞以及不符合团队规范的问题。我会结合通用编程最佳实践和您团队自定义的规则在references/中提供进行分析并提供具体的、可操作的改进建议。 ## 我的工作流程 1. **接收代码**请你提供需要审查的代码片段。可以是一个函数、一个类、一个文件或者一个Git Diff片段。 2. **理解上下文**我会询问或请你明确这段代码的编程语言、框架以及主要功能。 3. **分层审查**我将按照以下优先级进行分析 a. **功能性缺陷**明显的逻辑错误、边界条件缺失、可能的崩溃点。 b. **安全性问题**常见的安全漏洞如SQL注入、XSS、硬编码密钥等参考references/security_checklist.md。 c. **代码坏味道**过长的函数、过大的类、重复代码、过深的嵌套等参考references/code_smells.md。 d. **团队规范**命名约定、注释要求、导入顺序等参考references/team_style_guide.md。 e. **性能提示**低效的算法、不必要的数据库查询、内存泄漏风险等。 4. **生成报告**我会将发现的问题分类严重、警告、建议并针对每个问题提供 - **问题描述**哪里出了问题。 - **潜在风险**可能导致什么后果。 - **修改建议**具体的代码修改方案或最佳实践示例。 - **相关规则**引用了哪条团队规范或通用原则。 5. **交互与澄清**你可以随时问我某个问题的细节或让我忽略某些规则。审查不是一次性的我们可以迭代。 ## 如何使用我 - **直接审查**对我说“请审查这段代码[粘贴代码]” - **指定语言**“这是一段Python Flask代码请审查[代码]” - **聚焦某方面**“请重点审查这段代码的安全性[代码]” - **对比审查**“这是旧版本和新版本的Diff请看看改动引入了哪些风险[Git Diff]” ## 我的知识库 (references/) - security_checklist.md针对不同语言Python/JS/Java等的通用安全审查清单。 - code_smells.md经典的代码坏味道定义与示例。 - team_style_guide.md**请在此放置您团队的编码规范**。如果此文件为空我将仅使用通用规则。 ## 我的工具 (scripts/) - run_static_analysis.py一个示例脚本演示如何集成简单的本地静态分析工具如pylint, eslint。你可以根据团队情况修改和扩展它。 ## 重要提示 - 我是一个辅助工具不能替代人工深度审查和测试。 - 我的建议基于模式和规则可能产生误报或漏报请结合业务逻辑判断。 - 团队规范(team_style_guide.md)是提升审查相关性的关键请务必维护它。3.3 填充参考资料 (references/)这是Skill的“专业知识库”。我们创建几个示例文件references/security_checklist.md# 代码安全审查快速清单 ## Python - [ ] 输入验证所有用户输入是否经过验证和清理 - [ ] SQL注入是否使用参数化查询如SQLAlchemy ORM execute with params而非字符串拼接 - [ ] 命令注入os.system, subprocess.call 是否使用了不可信的用户输入 - [ ] 硬编码密钥密码、API密钥、令牌是否硬编码在源码中应使用环境变量或配置管理。 - [ ] 反序列化风险是否使用了pickle加载不可信数据 - [ ] 目录遍历文件操作路径是否使用了用户可控的输入而未做限制 ## JavaScript/Node.js - [ ] XSS防护输出到HTML的数据是否进行了正确的转义 - [ ] 依赖安全package.json中的依赖是否已知有高危漏洞可结合npm audit - [ ] 敏感信息泄露console.log是否可能打印出密码、令牌等 - [ ] 正则表达式拒绝服务(ReDoS)使用的正则表达式是否可能被恶意输入导致无限回溯 ...references/code_smells.md# 常见代码坏味道 ## 1. 过长函数 - **特征**一个函数超过50行可根据团队标准调整。 - **问题**难以理解、测试和维护。 - **重构建议**提取子函数每个函数只做一件事。 ## 2. 过大类 - **特征**一个类拥有过多属性或方法如超过10个。 - **问题**职责不清内聚性低。 - **重构建议**根据单一职责原则拆分。 ## 3. 重复代码 - **特征**两处或更多处代码结构高度相似。 - **问题**修改时需要多处同步易出错。 - **重构建议**提取公共函数、模板方法或使用继承/组合。 ...references/team_style_guide.md# 示例我们的团队Python风格指南 ## 命名约定 - 变量/函数名snake_case - 类名PascalCase - 常量UPPER_SNAKE_CASE - 私有成员前缀单下划线 _private_var ## 导入顺序 1. 标准库 2. 第三方库 3. 本地应用/模块 每组之间用空行分隔。 ## 注释要求 - 公共函数和类必须包含docstring。 - 复杂的逻辑块需要行内注释解释“为什么”而不是“做什么”。 ...这是一个模板实际使用时需要团队共同维护和更新3.4 开发工具脚本 (scripts/)为了让Skill更强大我们可以集成一些轻量级的自动化工具。例如一个调用本地代码分析工具的脚本scripts/run_static_analysis.py#!/usr/bin/env python3 一个简单的静态分析脚本包装器。 此脚本演示了如何在Skill中集成外部工具。 用户需要根据自身环境安装对应的分析工具如pylint, bandit, eslint等。 import subprocess import sys import json import os from pathlib import Path def run_pylint(code_content: str, temp_file_path: str /tmp/review_code.py) - dict: 使用pylint分析提供的Python代码。 将代码写入临时文件运行pylint并解析输出。 # 1. 将代码写入临时文件 with open(temp_file_path, w) as f: f.write(code_content) # 2. 运行pylint获取JSON格式输出 try: # 注意这里假设pylint已安装且可用。实际Skill中应增加错误处理。 result subprocess.run( [pylint, --output-formatjson, temp_file_path], capture_outputTrue, textTrue, timeout30 # 设置超时防止卡死 ) # 3. 清理临时文件 os.remove(temp_file_path) if result.returncode 0: # pylint返回0表示成功执行即使有错误输出可能在stdout output result.stdout or result.stderr else: output result.stderr # 尝试解析JSON输出 try: issues json.loads(output) # 简化输出提取关键信息 simplified_issues [] for issue in issues: simplified_issues.append({ type: issue.get(type, error).upper(), message: issue.get(message, ), line: issue.get(line), column: issue.get(column), symbol: issue.get(symbol) }) return {tool: pylint, issues: simplified_issues, raw_output: output[:500]} # 限制原始输出长度 except json.JSONDecodeError: # 如果不是JSON返回文本 return {tool: pylint, error: Failed to parse JSON output, raw_output: output[:1000]} except subprocess.TimeoutExpired: return {tool: pylint, error: Analysis timed out after 30 seconds.} except FileNotFoundError: return {tool: pylint, error: pylint command not found. Please install it (pip install pylint).} except Exception as e: return {tool: pylint, error: fUnexpected error: {str(e)}} def main(): 主函数演示如何被调用。 # 在实际Skill中这部分代码可能由AI根据上下文决定是否调用并传递代码内容。 # 这里我们模拟从标准输入或参数读取代码 if len(sys.argv) 1: # 从文件读取 with open(sys.argv[1], r) as f: code_to_review f.read() else: # 从标准输入读取例如通过管道 code_to_review sys.stdin.read() if not code_to_review.strip(): print(Error: No code content provided.) sys.exit(1) # 根据文件扩展名或内容判断语言这里简化为Python # 实际可以更智能地判断 analysis_result run_pylint(code_to_review) # 输出结果可以被AI读取 print(json.dumps(analysis_result, indent2)) if __name__ __main__: main()这个脚本展示了几个关键点封装性将复杂的命令行工具调用封装成一个简单的函数。错误处理考虑了工具未安装、超时、解析失败等情况。输出标准化将工具的原生输出转换为结构化的JSON方便AI理解和整合到它的审查报告中。安全边界使用临时文件设置超时避免无限循环或资源占用。在SKILL.md中你可以这样提示AI使用这个脚本对于Python代码你可以选择性地调用scripts/run_static_analysis.py来获取初步的静态分析结果。将代码内容通过标准输入传递给该脚本即可。请注意这需要运行环境已安装pylint。3.5 测试与迭代像开发产品一样开发SkillSkill开发完成后不要假设它就能完美工作。你需要进行测试功能测试提供不同类型的代码干净的、有错误的、风格混乱的看Skill能否正确识别并给出合理建议。边界测试输入空代码、非代码文本、超长代码看Skill如何处理。集成测试在目标环境如Claude Code, Cursor中安装并实际使用看整个交互流程是否顺畅。用户测试让目标用户其他开发者试用收集反馈。他们是否理解如何与Skill交互输出建议是否有用根据测试反馈回头修改SKILL.md的指令、补充references/的内容、或者优化scripts/的健壮性。Skill的开发是一个迭代过程。4. 超越单机Skill的分享、安装与生态思考当你有了一个成熟的Skill你可能会想分享给团队成员甚至发布到社区。这就涉及到Skill的“打包”和“分发”。4.1 如何“安装”一个Skill搜索材料中提到了多种安装方式其核心逻辑都是一致的将Skill文件夹放置到AI工具能够识别和加载的特定目录下。手动安装最简单直接将Skill文件夹复制到工具指定的Skills目录如Claude Desktop的~/Library/Application Support/Claude/Skills/。通过CLI工具安装这是更规范的方式。例如使用npx skills add github-repo或skillhub install skill-name。这些工具本质上也是帮你完成下载、解压、放置到正确目录的过程并可能管理版本和依赖。4.2 发布到Skill商店如果你想分享你的“代码审查助手”可以考虑完善文档在GitHub仓库的README中详细说明Skill的功能、安装方法、使用示例和配置要求。选择平台skills.sh (Vercel)一个Skill的发现和排行榜网站。将你的GitHub仓库链接提交过去。ClawHubOpenClaw的官方技能市场更偏向技术整合。SkillHub (腾讯)国内网络环境友好的技能市场。遵循规范确保你的Skill目录结构清晰SKILL.md描述准确没有恶意代码。4.3 安全警示Skill是一把双刃剑搜索材料中特别强调了安全问题这绝非危言耸听。一个Skill可能包含执行外部脚本的能力如我们的run_static_analysis.py。调用外部API的密钥如果脚本中硬编码了。访问本地文件系统。因此务必牢记作为使用者只从可信来源官方商店、知名开发者安装Skill。安装前查看Skill的源码特别是scripts/目录下的内容。作为开发者不要在你的Skill脚本中硬编码敏感信息。如果需要API密钥应通过环境变量或配置文件并提示用户自行配置来获取。在SKILL.md中明确声明你的Skill需要哪些权限以及为什么需要。5. 从Skill到Agent演进路径与长期价值最后让我们把视角拉高。Skill是构建智能体Agent的基石但它本身通常还不是一个完整的Agent。Skill解决一个特定、垂直的任务。它封装了“怎么做这件事”的知识和工具。Agent是一个具备自主规划、决策和工具调用能力的系统。它可以根据目标自主选择和使用一个或多个Skill来完成任务。你开发的“代码审查助手”是一个Skill。而一个“全自动代码质量守护Agent”可能会在代码提交时自动触发它先调用你的“代码审查助手”Skill进行分析如果发现问题则创建评论再调用“自动化测试”Skill运行测试最后调用“CI/CD集成”Skill来更新状态。这个Agent协调了多个Skill来完成一个更大的目标。所以学习开发Skill的真正长期价值在于模块化思维学会将复杂能力拆解成可复用、可组合的模块。人机协作设计深入思考哪些任务适合AI哪些需要人类干预如何设计流畅的交互接口。工程化实践接触到了结构化知识管理、工具封装、安全考量等工程问题。当你熟练掌握了Skill的开发你就拿到了构建更复杂、更自主AI系统的钥匙。你不再只是AI工具的使用者而是成为了为AI设计“专业能力”的塑造者。这条路从理解一个简单的文件夹结构开始通向的是人机协同工作的全新范式。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度如果你在2025年或2026年才开始关注AI Agent并且想从零开始学习如何开发一个真正能用的Agent Skill那么你很可能已经错过了最直观的入门窗口。现在你面对的不是一个清晰的学习路径而是一片由“框架”、“工具链”、“最佳实践”和“生态”构成的、令人眼花缭乱的术语丛林。你可能会看到无数教程告诉你“安装这个插件”、“使用那个命令”但很少有人告诉你为什么一个简单的“技能”需要如此复杂的结构以及从“跑通一个例子”到“开发一个能稳定工作的技能”之间到底隔着多少看不见的坑。这篇文章不会重复那些随处可见的安装命令列表。我想和你探讨的是在Agent Skill这个看似简单的概念背后隐藏着一种全新的、关于如何“教会”AI去完成特定任务的工程化思维。这种思维才是决定你能否从“会用”走向“会造”的关键。我们将从最根本的问题开始一个Skill到底是什么它为什么能工作然后我们会一步步拆解如何从零开始把一个模糊的想法变成一个结构清晰、可复用、甚至能分享给他人的标准化Skill。最后我们会深入到代码层面看看一个Skill的“骨架”和“血肉”究竟是如何构成的。1. 重新理解“Skill”它不只是个文件夹而是一套可复用的“工作记忆”很多人第一次接触Skill会把它理解成一个“插件”或“脚本包”。这个理解没错但太浅了。让我们换个角度Skill的本质是一套被结构化封装起来的“工作记忆”和“操作流程”。想象一下你每次让AI帮你写周报都需要重新解释一遍公司背景、你的岗位、本周重点、汇报对象、喜欢的格式……这是低效的重复。而一个“周报生成Skill”就是把所有这些背景信息、模板、写作要点打包成一个标准化的“知识包”。当你启用这个Skill时AI不是从零开始思考而是直接加载了这套预设的“工作记忆”瞬间进入“周报专家”的角色。这就是Skill与普通Prompt最核心的区别普通Prompt每次对话都是一次性的上下文。任务结束记忆清零。Skill将成功的任务经验背景、步骤、模板、规则沉淀为可复用的资产。下次需要时直接“调用”这套经验。所以当你看到Skill的标准目录结构时就能理解每个文件的作用了my-weekly-report-skill/ ├── SKILL.md # 核心定义这个Skill是什么、怎么用、输入输出是什么AI的“任务说明书” ├── references/ # 背景资料公司介绍、数据字典、行业术语AI的“参考资料库” ├── scripts/ # 可执行脚本数据获取、格式转换、调用APIAI的“自动化工具” └── assets/ # 静态资源报告模板、Logo图片、样式文件AI的“素材库”这个结构不是为了好看而是为了让AI能够按需、渐进式地加载和理解一个复杂任务。SKILL.md是总纲告诉AI任务目标当任务深入时AI可以根据需要去references/里查找细节或执行scripts/里的脚本来获取数据。1.1 为什么“结构化”如此重要你可能会问我把所有东西都写在一个巨大的Prompt里不行吗理论上可以但会立刻遇到两个天花板上下文长度限制再大的模型其上下文窗口也是有限的。一个包含数十个模板、大量背景知识的巨型Prompt会迅速耗尽宝贵的Token导致AI无法有效处理你的核心指令。认知负荷过载一次性给AI灌输所有信息就像给一个新员工第一天就扔给他一整本员工手册。他无法有效吸收和索引。结构化的好处在于按需加载AI只在需要用到某个部分时才去“翻阅”对应的文件这使得它的“思考”更聚焦、更高效。因此学习开发Skill的第一个思维转变就是从编写单次对话的Prompt转变为设计一套可被AI理解和执行的“程序化工作流”。1.2 Skill的两种核心范式“知识库型”与“工具调用型”根据Skill主要解决的问题我们可以将其分为两大类这决定了你的开发重心技能类型核心价值典型文件开发重点知识库型让AI掌握某个垂直领域的专业知识或公司内部信息。SKILL.md,references/信息的结构化整理、术语解释、案例库构建、检索逻辑设计。工具调用型赋予AI操作外部系统、处理数据或执行自动化任务的能力。SKILL.md,scripts/脚本的健壮性、错误处理、输入输出规范、API安全封装。当然很多优秀的Skill是两者的结合。例如一个“竞品分析Skill”既需要references/里存放市场报告和产品文档知识库也需要scripts/里的脚本来爬取最新的官网信息或应用商店评论工具调用。理解这个分类能帮助你在动手前就想清楚我这个Skill到底要解决哪一类问题我的主要精力应该放在整理资料上还是编写可靠的脚本上2. 从想法到蓝图如何系统化地设计你的第一个Skill不要一上来就打开编辑器写SKILL.md。那大概率会写出一个混乱、边界模糊、难以使用的Skill。正确的起点是进行任务拆解与蓝图设计。2.1 第一步用“用户故事”定义清晰边界问自己几个问题谁会用这个Skill开发者、运营、设计师在什么场景下用写代码时、做周报时、分析数据时用户的核心目标是什么用一句话描述例如“快速生成符合公司规范的API接口文档”完成这个目标需要哪些输入接口定义JSON功能描述文字成功的输出是什么一个格式良好的Markdown文档一个包含示例的Swagger文件把这些答案写下来就是一个最简单的“用户故事”。它能帮你牢牢锁定Skill的核心功能避免陷入“什么功能都想加”的陷阱。2.2 第二步拆解任务流程划分“人机协作”边界接下来把用户目标拆解成具体的步骤。关键是要想清楚哪些步骤AI擅长理解、生成、规划哪些步骤需要外部工具或人工干预获取实时数据、执行系统命令、人工审核。以“生成API文档”为例输入解析AI擅长。理解用户提供的接口描述或代码片段。信息补全AI擅长。根据惯例补全可能的请求头、状态码说明、错误示例。模板填充AI擅长。将结构化信息填入预设的Markdown模板。实时数据获取AI不擅长。如果需要从线上Swagger服务器拉取最新定义就需要一个scripts/fetch_swagger.py。格式校验与发布可能混合。AI可以校验基本格式但发布到Confluence或生成PDF可能需要另一个脚本。这个拆解过程直接决定了你的Skill目录里需要哪些文件。步骤1-3主要靠SKILL.md中的指令和assets/template.md步骤4需要一个脚本步骤5可能还需要一个脚本或明确的后续手动步骤说明。2.3 第三步设计SKILL.md——AI的“任务手册”SKILL.md是Skill的灵魂。它不应该是一堆命令的堆砌而应该像一份优秀的项目说明书或操作手册。一个结构清晰的SKILL.md通常包含以下部分# Skill名称API文档生成助手 ## 技能描述 本技能用于帮助开发者快速生成标准、易读的API接口文档。它能够解析接口定义自动补全常见字段并套用可定制的模板输出Markdown格式文档。 ## 核心能力 - 解析自然语言描述的接口功能生成结构化定义。 - 支持从代码片段如Python Flask装饰器中提取接口信息。 - 提供多种文档模板基础版、详细版、团队内部版。 - 可选的Swagger JSON同步功能需配置。 ## 如何使用 1. **激活技能**在对话中提及“生成API文档”或直接使用本技能。 2. **提供输入**你可以 - 直接描述接口如“需要一个用户登录的POST接口路径是/auth/login接收用户名和密码。” - 粘贴代码片段。 - 提供一个现有的Swagger JSON路径需要提前运行同步脚本。 3. **交互与调整**我会根据你的输入生成草案你可以要求我调整任何部分。 4. **获取输出**最终文档将以Markdown格式提供你可以直接复制使用。 ## 文件与资源说明 - references/api_guidelines.md本团队内部的API设计规范生成文档时会参考此规范。 - assets/template_basic.md基础文档模板。 - assets/template_detailed.md包含更多示例和说明的详细模板。 - scripts/sync_from_swagger.py从远程Swagger URL拉取最新定义的脚本。**使用前需要配置目标URL**。 ## 注意事项 - 生成的文档需人工复核业务逻辑准确性。 - 同步脚本需要网络权限且仅支持标准的Swagger 2.0/OpenAPI 3.0格式。 - 技能不存储任何输入的接口数据。这份“手册”明确了技能的目的、用法、边界和依赖让AI和用户都能清晰理解如何协作。3. 实战开发构建一个“代码审查助手”Skill让我们通过一个相对复杂的例子——“代码审查助手”将上述设计理念付诸实践。这个Skill的目标是帮助开发者在提交代码前快速进行一轮基于最佳实践的自动化审查。3.1 项目初始化与结构搭建首先创建标准的Skill目录结构mkdir code-review-assistant cd code-review-assistant mkdir -p references scripts assets touch SKILL.md3.2 编写核心SKILL.md这是最关键的部分它定义了整个Skill的行为逻辑。# Skill名称智能代码审查助手 ## 技能描述 我是一个专注于代码质量审查的助手。我的目标是帮助你提前发现代码中可能存在的缺陷、坏味道、安全漏洞以及不符合团队规范的问题。我会结合通用编程最佳实践和您团队自定义的规则在references/中提供进行分析并提供具体的、可操作的改进建议。 ## 我的工作流程 1. **接收代码**请你提供需要审查的代码片段。可以是一个函数、一个类、一个文件或者一个Git Diff片段。 2. **理解上下文**我会询问或请你明确这段代码的编程语言、框架以及主要功能。 3. **分层审查**我将按照以下优先级进行分析 a. **功能性缺陷**明显的逻辑错误、边界条件缺失、可能的崩溃点。 b. **安全性问题**常见的安全漏洞如SQL注入、XSS、硬编码密钥等参考references/security_checklist.md。 c. **代码坏味道**过长的函数、过大的类、重复代码、过深的嵌套等参考references/code_smells.md。 d. **团队规范**命名约定、注释要求、导入顺序等参考references/team_style_guide.md。 e. **性能提示**低效的算法、不必要的数据库查询、内存泄漏风险等。 4. **生成报告**我会将发现的问题分类严重、警告、建议并针对每个问题提供 - **问题描述**哪里出了问题。 - **潜在风险**可能导致什么后果。 - **修改建议**具体的代码修改方案或最佳实践示例。 - **相关规则**引用了哪条团队规范或通用原则。 5. **交互与澄清**你可以随时问我某个问题的细节或让我忽略某些规则。审查不是一次性的我们可以迭代。 ## 如何使用我 - **直接审查**对我说“请审查这段代码[粘贴代码]” - **指定语言**“这是一段Python Flask代码请审查[代码]” - **聚焦某方面**“请重点审查这段代码的安全性[代码]” - **对比审查**“这是旧版本和新版本的Diff请看看改动引入了哪些风险[Git Diff]” ## 我的知识库 (references/) - security_checklist.md针对不同语言Python/JS/Java等的通用安全审查清单。 - code_smells.md经典的代码坏味道定义与示例。 - team_style_guide.md**请在此放置您团队的编码规范**。如果此文件为空我将仅使用通用规则。 ## 我的工具 (scripts/) - run_static_analysis.py一个示例脚本演示如何集成简单的本地静态分析工具如pylint, eslint。你可以根据团队情况修改和扩展它。 ## 重要提示 - 我是一个辅助工具不能替代人工深度审查和测试。 - 我的建议基于模式和规则可能产生误报或漏报请结合业务逻辑判断。 - 团队规范(team_style_guide.md)是提升审查相关性的关键请务必维护它。3.3 填充参考资料 (references/)这是Skill的“专业知识库”。我们创建几个示例文件references/security_checklist.md# 代码安全审查快速清单 ## Python - [ ] 输入验证所有用户输入是否经过验证和清理 - [ ] SQL注入是否使用参数化查询如SQLAlchemy ORM execute with params而非字符串拼接 - [ ] 命令注入os.system, subprocess.call 是否使用了不可信的用户输入 - [ ] 硬编码密钥密码、API密钥、令牌是否硬编码在源码中应使用环境变量或配置管理。 - [ ] 反序列化风险是否使用了pickle加载不可信数据 - [ ] 目录遍历文件操作路径是否使用了用户可控的输入而未做限制 ## JavaScript/Node.js - [ ] XSS防护输出到HTML的数据是否进行了正确的转义 - [ ] 依赖安全package.json中的依赖是否已知有高危漏洞可结合npm audit - [ ] 敏感信息泄露console.log是否可能打印出密码、令牌等 - [ ] 正则表达式拒绝服务(ReDoS)使用的正则表达式是否可能被恶意输入导致无限回溯 ...references/code_smells.md# 常见代码坏味道 ## 1. 过长函数 - **特征**一个函数超过50行可根据团队标准调整。 - **问题**难以理解、测试和维护。 - **重构建议**提取子函数每个函数只做一件事。 ## 2. 过大类 - **特征**一个类拥有过多属性或方法如超过10个。 - **问题**职责不清内聚性低。 - **重构建议**根据单一职责原则拆分。 ## 3. 重复代码 - **特征**两处或更多处代码结构高度相似。 - **问题**修改时需要多处同步易出错。 - **重构建议**提取公共函数、模板方法或使用继承/组合。 ...references/team_style_guide.md# 示例我们的团队Python风格指南 ## 命名约定 - 变量/函数名snake_case - 类名PascalCase - 常量UPPER_SNAKE_CASE - 私有成员前缀单下划线 _private_var ## 导入顺序 1. 标准库 2. 第三方库 3. 本地应用/模块 每组之间用空行分隔。 ## 注释要求 - 公共函数和类必须包含docstring。 - 复杂的逻辑块需要行内注释解释“为什么”而不是“做什么”。 ...这是一个模板实际使用时需要团队共同维护和更新3.4 开发工具脚本 (scripts/)为了让Skill更强大我们可以集成一些轻量级的自动化工具。例如一个调用本地代码分析工具的脚本scripts/run_static_analysis.py#!/usr/bin/env python3 一个简单的静态分析脚本包装器。 此脚本演示了如何在Skill中集成外部工具。 用户需要根据自身环境安装对应的分析工具如pylint, bandit, eslint等。 import subprocess import sys import json import os from pathlib import Path def run_pylint(code_content: str, temp_file_path: str /tmp/review_code.py) - dict: 使用pylint分析提供的Python代码。 将代码写入临时文件运行pylint并解析输出。 # 1. 将代码写入临时文件 with open(temp_file_path, w) as f: f.write(code_content) # 2. 运行pylint获取JSON格式输出 try: # 注意这里假设pylint已安装且可用。实际Skill中应增加错误处理。 result subprocess.run( [pylint, --output-formatjson, temp_file_path], capture_outputTrue, textTrue, timeout30 # 设置超时防止卡死 ) # 3. 清理临时文件 os.remove(temp_file_path) if result.returncode 0: # pylint返回0表示成功执行即使有错误输出可能在stdout output result.stdout or result.stderr else: output result.stderr # 尝试解析JSON输出 try: issues json.loads(output) # 简化输出提取关键信息 simplified_issues [] for issue in issues: simplified_issues.append({ type: issue.get(type, error).upper(), message: issue.get(message, ), line: issue.get(line), column: issue.get(column), symbol: issue.get(symbol) }) return {tool: pylint, issues: simplified_issues, raw_output: output[:500]} # 限制原始输出长度 except json.JSONDecodeError: # 如果不是JSON返回文本 return {tool: pylint, error: Failed to parse JSON output, raw_output: output[:1000]} except subprocess.TimeoutExpired: return {tool: pylint, error: Analysis timed out after 30 seconds.} except FileNotFoundError: return {tool: pylint, error: pylint command not found. Please install it (pip install pylint).} except Exception as e: return {tool: pylint, error: fUnexpected error: {str(e)}} def main(): 主函数演示如何被调用。 # 在实际Skill中这部分代码可能由AI根据上下文决定是否调用并传递代码内容。 # 这里我们模拟从标准输入或参数读取代码 if len(sys.argv) 1: # 从文件读取 with open(sys.argv[1], r) as f: code_to_review f.read() else: # 从标准输入读取例如通过管道 code_to_review sys.stdin.read() if not code_to_review.strip(): print(Error: No code content provided.) sys.exit(1) # 根据文件扩展名或内容判断语言这里简化为Python # 实际可以更智能地判断 analysis_result run_pylint(code_to_review) # 输出结果可以被AI读取 print(json.dumps(analysis_result, indent2)) if __name__ __main__: main()这个脚本展示了几个关键点封装性将复杂的命令行工具调用封装成一个简单的函数。错误处理考虑了工具未安装、超时、解析失败等情况。输出标准化将工具的原生输出转换为结构化的JSON方便AI理解和整合到它的审查报告中。安全边界使用临时文件设置超时避免无限循环或资源占用。在SKILL.md中你可以这样提示AI使用这个脚本对于Python代码你可以选择性地调用scripts/run_static_analysis.py来获取初步的静态分析结果。将代码内容通过标准输入传递给该脚本即可。请注意这需要运行环境已安装pylint。3.5 测试与迭代像开发产品一样开发SkillSkill开发完成后不要假设它就能完美工作。你需要进行测试功能测试提供不同类型的代码干净的、有错误的、风格混乱的看Skill能否正确识别并给出合理建议。边界测试输入空代码、非代码文本、超长代码看Skill如何处理。集成测试在目标环境如Claude Code, Cursor中安装并实际使用看整个交互流程是否顺畅。用户测试让目标用户其他开发者试用收集反馈。他们是否理解如何与Skill交互输出建议是否有用根据测试反馈回头修改SKILL.md的指令、补充references/的内容、或者优化scripts/的健壮性。Skill的开发是一个迭代过程。4. 超越单机Skill的分享、安装与生态思考当你有了一个成熟的Skill你可能会想分享给团队成员甚至发布到社区。这就涉及到Skill的“打包”和“分发”。4.1 如何“安装”一个Skill搜索材料中提到了多种安装方式其核心逻辑都是一致的将Skill文件夹放置到AI工具能够识别和加载的特定目录下。手动安装最简单直接将Skill文件夹复制到工具指定的Skills目录如Claude Desktop的~/Library/Application Support/Claude/Skills/。通过CLI工具安装这是更规范的方式。例如使用npx skills add github-repo或skillhub install skill-name。这些工具本质上也是帮你完成下载、解压、放置到正确目录的过程并可能管理版本和依赖。4.2 发布到Skill商店如果你想分享你的“代码审查助手”可以考虑完善文档在GitHub仓库的README中详细说明Skill的功能、安装方法、使用示例和配置要求。选择平台skills.sh (Vercel)一个Skill的发现和排行榜网站。将你的GitHub仓库链接提交过去。ClawHubOpenClaw的官方技能市场更偏向技术整合。SkillHub (腾讯)国内网络环境友好的技能市场。遵循规范确保你的Skill目录结构清晰SKILL.md描述准确没有恶意代码。4.3 安全警示Skill是一把双刃剑搜索材料中特别强调了安全问题这绝非危言耸听。一个Skill可能包含执行外部脚本的能力如我们的run_static_analysis.py。调用外部API的密钥如果脚本中硬编码了。访问本地文件系统。因此务必牢记作为使用者只从可信来源官方商店、知名开发者安装Skill。安装前查看Skill的源码特别是scripts/目录下的内容。作为开发者不要在你的Skill脚本中硬编码敏感信息。如果需要API密钥应通过环境变量或配置文件并提示用户自行配置来获取。在SKILL.md中明确声明你的Skill需要哪些权限以及为什么需要。5. 从Skill到Agent演进路径与长期价值最后让我们把视角拉高。Skill是构建智能体Agent的基石但它本身通常还不是一个完整的Agent。Skill解决一个特定、垂直的任务。它封装了“怎么做这件事”的知识和工具。Agent是一个具备自主规划、决策和工具调用能力的系统。它可以根据目标自主选择和使用一个或多个Skill来完成任务。你开发的“代码审查助手”是一个Skill。而一个“全自动代码质量守护Agent”可能会在代码提交时自动触发它先调用你的“代码审查助手”Skill进行分析如果发现问题则创建评论再调用“自动化测试”Skill运行测试最后调用“CI/CD集成”Skill来更新状态。这个Agent协调了多个Skill来完成一个更大的目标。所以学习开发Skill的真正长期价值在于模块化思维学会将复杂能力拆解成可复用、可组合的模块。人机协作设计深入思考哪些任务适合AI哪些需要人类干预如何设计流畅的交互接口。工程化实践接触到了结构化知识管理、工具封装、安全考量等工程问题。当你熟练掌握了Skill的开发你就拿到了构建更复杂、更自主AI系统的钥匙。你不再只是AI工具的使用者而是成为了为AI设计“专业能力”的塑造者。这条路从理解一个简单的文件夹结构开始通向的是人机协同工作的全新范式。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
