技能创建者：构建有效的Claude技能

--- name: skill-creator description: 用于创建有效技能的指南。当用户想要创建新技能（或更新现有技能）以扩展Claude的能力，提供专业知识、工作流程或工具集成时，应使用此技能。 license: 完整条款见LICENSE.txt --- # 技能创建器 此技能提供创建有效技能的指导。 ## 关于技能 技能是模块化、自包含的包，通过提供专业知识、工作流程和工具来扩展Claude的能力。可以将它们视为特定领域或任务的"入职指南"，它们将Claude从通用代理转变为配备程序性知识的专业代理，这些知识是任何模型都无法完全拥有的。 ### 技能提供的内容 1. 专业工作流程 - 针对特定领域的多步骤流程 2. 工具集成 - 处理特定文件格式或API的说明 3. 领域专业知识 - 公司特定知识、模式、业务逻辑 4. 捆绑资源 - 用于复杂和重复性任务的脚本、参考资料和资产 ## 核心原则 ### 简洁是关键 上下文窗口是公共资源。技能与Claude需要的所有其他内容共享上下文窗口：系统提示、对话历史、其他技能的元数据以及实际用户请求。 **默认假设：Claude已经非常聪明。** 只添加Claude尚未拥有的上下文。质疑每条信息："Claude真的需要这个解释吗？"以及"这段文字是否值得其token成本？" 优先使用简洁的示例，而非冗长的解释。 ### 设置适当的自由度 将特定程度与任务的脆弱性和可变性相匹配： **高自由度（基于文本的指令）**：当多种方法都有效、决策取决于上下文或启发式方法指导方法时使用。 **中等自由度（带参数的伪代码或脚本）**：当存在首选模式、允许一定变化或配置影响行为时使用。 **低自由度（特定脚本、少量参数）**：当操作脆弱且容易出错、一致性至关重要或必须遵循特定顺序时使用。 将Claude视为探索路径：狭窄的桥梁和悬崖需要特定的护栏（低自由度），而开阔的田野允许多种路线（高自由度）。 ### 技能的构成 每个技能由必需的SKILL.md文件和可选的捆绑资源组成： ``` skill-name/ ├── SKILL.md（必需） │ ├── YAML frontmatter元数据（必需） │ │ ├── name：（必需） │ │ └── description：（必需） │ └── Markdown指令（必需） └── 捆绑资源（可选） ├── scripts/ - 可执行代码（Python/Bash等） ├── references/ - 根据需要加载到上下文中的文档 └── assets/ - 用于输出的文件（模板、图标、字体等） ``` #### SKILL.md（必需） 每个SKILL.md包含： - **Frontmatter**（YAML）：包含`name`和`description`字段。这些是Claude读取的唯一字段，用于确定何时使用技能，因此在描述技能是什么以及何时使用它时，清晰和全面非常重要。 - **正文**（Markdown）：使用技能的说明和指导。仅在技能触发后加载（如果有的话）。 #### 捆绑资源（可选） ##### 脚本（`scripts/`） 可执行代码（Python/Bash等），用于需要确定性可靠性或反复重写的任务。 - **何时包含**：当相同代码被反复重写或需要确定性可靠性时 - **示例**：用于PDF旋转任务的`scripts/rotate_pdf.py` - **优势**：token高效、确定性、无需加载到上下文即可执行 - **注意**：Claude可能仍需要读取脚本以进行修补或特定环境的调整 ##### 参考资料（`references/`） 旨在根据需要加载到上下文中的文档和参考资料，以指导Claude的流程和思考。 - **何时包含**：对于Claude在工作时应参考的文档 - **示例**：用于财务模式的`references/finance.md`、用于公司NDA模板的`references/mnda.md`、用于公司政策的`references/policies.md`、用于API规范的`references/api_docs.md` - **使用场景**：数据库模式、API文档、领域知识、公司政策、详细工作流程指南 - **优势**：保持SKILL.md精简，仅在Claude确定需要时加载 - **最佳实践**：如果文件较大（超过10k字），在SKILL.md中包含grep搜索模式 - **避免重复**：信息应存在于SKILL.md或参考资料文件中，而非两者。 ##### 资产（`assets/`） 不打算加载到上下文中的文件，而是用于Claude产生的输出中。 - **何时包含**：当技能需要将用于最终输出的文件时 - **示例**：用于品牌资产的`assets/logo.png`、用于PowerPoint模板的`assets/slides.pptx` - **使用场景**：模板、图像、图标、样板代码、字体、示例文档 ### 渐进式披露设计原则 技能使用三级加载系统来有效管理上下文： 1. **元数据（name + description）** - 始终在上下文中（约100字） 2. **SKILL.md正文** - 当技能触发时（少于5k字） 3. **捆绑资源** - 根据需要由Claude加载 保持SKILL.md正文精简，控制在500行以内，以最小化上下文膨胀。 ## 技能创建流程 技能创建涉及以下步骤： 1. 通过具体示例理解技能 2. 规划可复用的技能内容（脚本、参考资料、资产） 3. 初始化技能（运行init_skill.py） 4. 编辑技能（实现资源并编写SKILL.md） 5. 打包技能（运行package_skill.py） 6. 根据实际使用情况进行迭代 ### 步骤3：初始化技能 从头创建新技能时，始终运行`init_skill.py`脚本： ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` ### 步骤4：编辑技能 根据技能需求参考以下有用指南： - **多步骤流程**：参见references/workflows.md了解顺序工作流程和条件逻辑 - **特定输出格式或质量标准**：参见references/output-patterns.md了解模板和示例模式 ### 步骤5：打包技能 ```bash scripts/package_skill.py <path/to/skill-folder> ``` 打包脚本验证并创建用于分发的.skill文件。 文件：references/workflows.md # 工作流程模式 ## 顺序工作流程 对于复杂任务，将操作分解为清晰、顺序的步骤。在SKILL.md开头向Claude提供流程概述通常很有帮助： ```markdown 填写PDF表单涉及以下步骤： 1. 分析表单（运行analyze_form.py） 2. 创建字段映射（编辑fields.json） 3. 验证映射（运行validate_fields.py） 4. 填写表单（运行fill_form.py） 5. 验证输出（运行verify_output.py） ``` ## 条件工作流程 对于具有分支逻辑的任务，指导Claude通过决策点： ```markdown 1. 确定修改类型： **创建新内容？** → 按照下面的"创建工作流程" **编辑现有内容？** → 按照下面的"编辑工作流程" 2. 创建工作流程：[步骤] 3. 编辑工作流程：[步骤] ``` 文件：references/output-patterns.md # 输出模式 当技能需要产生一致、高质量的输出时，使用这些模式。 ## 模板模式 为输出格式提供模板。将严格程度与需求相匹配。 **对于严格要求（如API响应或数据格式）：** ```markdown ## 报告结构 始终使用此确切模板结构： # [分析标题] ## 执行摘要 [关键发现的一段概述] ## 关键发现 - 发现1及支持数据 - 发现2及支持数据 - 发现3及支持数据 ## 建议 1. 具体的可操作建议 2. 具体的可操作建议 ``` **对于灵活指导（当适应有用时）：** ```markdown ## 报告结构 这是一个合理的默认格式，但请运用最佳判断： # [分析标题] ## 执行摘要 [概述] ## 关键发现 [根据发现调整部分] ## 建议 [针对具体上下文定制] 根据具体分析类型调整部分。 ``` ## 示例模式 对于输出质量取决于查看示例的技能，提供输入/输出对： ```markdown ## 提交消息格式 按照以下示例生成提交消息： **示例1：** 输入：添加了使用JWT令牌的用户认证 输出： ``` feat(auth)：实现基于JWT的认证 添加登录端点和令牌验证中间件 ``` **示例2：** 输入：修复了报告中日期显示不正确的问题 输出： ``` fix(reports)：修正时区转换中的日期格式 在报告生成中一致使用UTC时间戳 ``` 遵循此风格：type(scope)：简要描述，然后详细说明。 ``` 示例帮助Claude比仅描述更清晰地理解所需风格和详细程度。 文件：scripts/quick_validate.py #!/usr/bin/env python3 """ 技能的快速验证脚本 - 最小版本 """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """技能的基本验证""" skill_path = Path(skill_path) # 检查SKILL.md是否存在 skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "未找到SKILL.md" # 读取并验证frontmatter content = skill_md.read_text() if not content.startswith('---'): return False, "未找到YAML frontmatter" # 提取frontmatter match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "frontmatter格式无效" frontmatter_text = match.group(1) # 解析YAML frontmatter try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "frontmatter必须是YAML字典" except yaml.YAMLError as e: return False, f"frontmatter中的YAML无效：{e}" # 定义允许的属性 ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # 检查意外属性（排除metadata下的嵌套键） unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"SKILL.md frontmatter中存在意外键：{', '.join(sorted(unexpected_keys))}。" f"允许的属性为：{', '.join(sorted(ALLOWED_PROPERTIES))}" ) # 检查必填字段 if 'name' not in frontmatter: return False, "frontmatter中缺少'name'" if 'description' not in frontmatter: return False, "frontmatter中缺少'description'" # 提取name进行验证 name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"name必须是字符串，实际为{type(name).__name__}" name = name.strip() if name: # 检查命名约定（连字符格式：小写字母和连字符） if not re.match(r'^[a-z0-9-]+$', name): return False, f"name '{name}'应为连字符格式（仅小写字母、数字和连字符）" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"name '{name}'不能以连字符开头/结尾或包含连续连字符" # 检查name长度（根据规范最大64个字符） if len(name) > 64: return False, f"name过长（{len(name)}个字符）。最大为64个字符。" # 提取并验证description description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"description必须是字符串，实际为{type(description).__name__}" description = description.strip() if description: # 检查尖括号 if '<' in description or '>' in description: return False, "description不能包含尖括号（<或>）" # 检查description长度（根据规范最大1024个字符） if len(description) > 1024: return False, f"description过长（{len(description)}个字符）。最大为1024个字符。" return True, "技能有效！" if __name__ == "__main__": if len(sys.argv) != 2: print("用法：python quick_validate.py <skill_directory>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) 文件：scripts/init_skill.py #!/usr/bin/env python3 """ 技能初始化器 - 从模板创建新技能 用法： init_skill.py <skill-name> --path <path> 示例： init_skill.py my-new-skill --path skills/public init_skill.py my-api-helper --path skills/private init_skill.py custom-skill --path /custom/location """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [TODO：完成技能功能及使用时机信息的说明。包括何时使用此技能 - 触发它的特定场景、文件类型或任务。] --- # {skill_title} ## 概述 [TODO：1-2句话说明此技能支持的功能] ## 资源 此技能包含示例资源目录，演示如何组织不同类型的捆绑资源： ### scripts/ 可执行代码（Python/Bash等），可直接运行以执行特定操作。 ### references/ 旨在加载到上下文中的文档和参考资料，以指导Claude的流程和思考。 ### assets/ 不打算加载到上下文中的文件，而是用于Claude产生的输出中。 --- **任何不需要的目录都可以删除。** 并非每个技能都需要所有三种类型的资源。 """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ {skill_name}的示例辅助脚本 这是一个可直接执行的占位脚本。 替换为实际实现，如果不需要则删除。 """ def main(): print("这是{skill_name}的示例脚本") # TODO：在此添加实际脚本逻辑 if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# {skill_title}的参考文档 这是详细参考文档的占位符。 替换为实际参考内容，如果不需要则删除。 """ EXAMPLE_ASSET = """# 示例资产文件 此占位符代表资产文件的存储位置。 替换为实际资产文件（模板、图像、字体等），如果不需要则删除。 """ def title_case_skill_name(skill_name): """将连字符技能名称转换为标题格式以进行显示。""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """使用模板SKILL.md初始化新技能目录。""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ 错误：技能目录已存在：{skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ 已创建技能目录：{skill_dir}") except Exception as e: print(f"❌ 创建目录时出错：{e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ 已创建SKILL.md") except Exception as e: print(f"❌ 创建SKILL.md时出错：{e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ 已创建scripts/example.py") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ 已创建references/api_reference.md") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ 已创建assets/example_asset.txt") except Exception as e: print(f"❌ 创建资源目录时出错：{e}") return None print(f"\n✅ 技能'{skill_name}'已在{skill_dir}成功初始化") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("用法：init_skill.py <skill-name> --path <path>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 正在初始化技能：{skill_name}") print(f" 位置：{path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() 文件：scripts/package_skill.py #!/usr/bin/env python3 """ 技能打包器 - 创建技能文件夹的可分发.skill文件 用法： python utils/package_skill.py <path/to/skill-folder> [output-directory] 示例： python utils/package_skill.py skills/public/my-skill python utils/package_skill.py skills/public/my-skill ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """将技能文件夹打包为.skill文件。""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ 错误：未找到技能文件夹：{skill_path}") return None if not skill_path.is_dir(): print(f"❌ 错误：路径不是目录：{skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ 错误：在{skill_path}中未找到SKILL.md") return None print("🔍 正在验证技能...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ 验证失败：{message}") print(" 请在打包前修复验证错误。") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" 已添加：{arcname}") print(f"\n✅ 成功将技能打包到：{skill_filename}") return skill_filename except Exception as e: print(f"❌ 创建.skill文件时出错：{e}") return None def main(): if len(sys.argv) < 2: print("用法：python utils/package_skill.py <path/to/skill-folder> [output-directory]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 正在打包技能：{skill_path}") if output_dir: print(f" 输出目录：{output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()