@liangjie559567/ultrapower 5.6.6 → 5.6.8

package/skills/writing-skills/anthropic-best-practices.md

@@ -13,8 +13,11 @@
 [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) 是公共资源。你的 Skill 与 Claude 需要了解的所有其他内容共享 context window，包括：
 
 * 系统提示
+
 * 对话历史
+
 * 其他 Skill 的元数据
+
 * 你的实际请求
 
 并非 Skill 中的每个 token 都有即时成本。启动时，只有所有 Skill 的元数据（名称和描述）被预加载。Claude 仅在 Skill 变得相关时才读取 SKILL.md，并仅在需要时读取其他文件。然而，在 SKILL.md 中保持简洁仍然重要：一旦 Claude 加载它，每个 token 都与对话历史和其他上下文竞争。
@@ -24,12 +27,15 @@
 只添加 Claude 尚未拥有的上下文。对每条信息提出质疑：
 
 * "Claude 真的需要这个解释吗？"
+
 * "我可以假设 Claude 知道这个吗？"
+
 * "这段话值得其 token 成本吗？"
 
 **好示例：简洁**（约 50 个 token）：
 
 ````markdown
+
 ## 提取 PDF 文本
 
 使用 pdfplumber 进行文本提取：
@@ -45,6 +51,7 @@ with pdfplumber.open("file.pdf") as pdf:
 **坏示例：过于冗长**（约 150 个 token）：
 
 ```markdown
+
 ## 提取 PDF 文本
 
 PDF（便携式文档格式）文件是一种常见的文件格式，包含
@@ -65,12 +72,15 @@ PDF（便携式文档格式）文件是一种常见的文件格式，包含
 使用时机：
 
 * 多种方法都有效
+
 * 决策取决于上下文
+
 * 启发式方法指导方式
 
 示例：
 
 ```markdown
+
 ## 代码审查流程
 
 1. 分析代码结构和组织
@@ -84,12 +94,15 @@ PDF（便携式文档格式）文件是一种常见的文件格式，包含
 使用时机：
 
 * 存在首选模式
+
 * 可以接受一些变化
+
 * 配置影响行为
 
 示例：
 
 ````markdown
+
 ## 生成报告
 
 使用此模板并根据需要自定义：
@@ -107,12 +120,15 @@ def generate_report(data, format="markdown", include_charts=True):
 使用时机：
 
 * 操作脆弱且容易出错
+
 * 一致性至关重要
+
 * 必须遵循特定顺序
 
 示例：
 
 ````markdown
+
 ## 数据库迁移
 
 精确运行此脚本：
@@ -127,6 +143,7 @@ python scripts/migrate.py --verify --backup
 **类比**：将 Claude 想象为探索路径的机器人：
 
 * **两侧有悬崖的窄桥**：只有一条安全的前进路径。提供具体的护栏和精确指令（低自由度）。示例：必须按精确顺序运行的数据库迁移。
+
 * **没有危险的开阔田野**：许多路径都能成功。给出大方向并信任 Claude 找到最佳路线（高自由度）。示例：上下文决定最佳方法的代码审查。
 
 ### 使用你计划使用的所有模型进行测试
@@ -136,7 +153,9 @@ Skill 作为模型的补充，因此有效性取决于底层模型。使用你
 **按模型的测试考虑**：
 
 * **Claude Haiku**（快速、经济）：Skill 是否提供了足够的指导？
+
 * **Claude Sonnet**（平衡）：Skill 是否清晰高效？
+
 * **Claude Opus**（强大推理）：Skill 是否避免了过度解释？
 
 对 Opus 完美有效的内容可能需要为 Haiku 提供更多细节。如果你计划在多个模型中使用 Skill，目标是编写对所有模型都有效的指令。
@@ -159,27 +178,37 @@ Skill 作为模型的补充，因此有效性取决于底层模型。使用你
 **好的命名示例（动名词形式）**：
 
 * "Processing PDFs"
+
 * "Analyzing spreadsheets"
+
 * "Managing databases"
+
 * "Testing code"
+
 * "Writing documentation"
 
 **可接受的替代方案**：
 
 * 名词短语："PDF Processing"、"Spreadsheet Analysis"
+
 * 动作导向："Process PDFs"、"Analyze Spreadsheets"
 
 **避免**：
 
 * 模糊名称："Helper"、"Utils"、"Tools"
+
 * 过于通用："Documents"、"Data"、"Files"
+
 * 在 skill 集合中使用不一致的模式
 
 一致的命名使以下操作更容易：
 
 * 在文档和对话中引用 Skill
+
 * 一眼了解 Skill 的功能
+
 * 组织和搜索多个 Skill
+
 * 维护专业、统一的 skill 库
 
 ### 编写有效的描述
@@ -239,7 +268,9 @@ SKILL.md 作为概述，根据需要将 Claude 指向详细材料，就像入职
 **实用指导：**
 
 * 保持 SKILL.md 正文在 500 行以内以获得最佳性能
+
 * 接近此限制时将内容拆分为单独文件
+
 * 使用以下模式有效组织指令、代码和资源
 
 #### 完整的 Skill 目录结构示例：
@@ -303,6 +334,7 @@ bigquery-skill/
 显示基本内容，链接到高级内容：
 
 ```markdown
+
 # DOCX Processing
 
 ## Creating documents
@@ -328,19 +360,24 @@ Claude 仅在用户需要这些功能时才读取 REDLINING.md 或 OOXML.md。
 **坏示例：太深**：
 
 ```markdown
+
 # SKILL.md
+
 See [advanced.md](advanced.md)...
 
 # advanced.md
+
 See [details.md](details.md)...
 
 # details.md
+
 Here's the actual information...
 ```
 
 **好示例：一层深**：
 
 ```markdown
+
 # SKILL.md
 
 **Basic usage**: [instructions in SKILL.md]
@@ -356,19 +393,27 @@ Here's the actual information...
 **示例**：
 
 ```markdown
+
 # API Reference
 
 ## Contents
-- Authentication and setup
-- Core methods (create, read, update, delete)
-- Advanced features (batch operations, webhooks)
-- Error handling patterns
-- Code examples
+
+* Authentication and setup
+
+* Core methods (create, read, update, delete)
+
+* Advanced features (batch operations, webhooks)
+
+* Error handling patterns
+
+* Code examples
 
 ## Authentication and setup
+
 ...
 
 ## Core methods
+
 ...
 ```
 
@@ -383,17 +428,23 @@ Claude 可以根据需要读取完整文件或跳转到特定部分。
 **示例 1：研究综合工作流**（适用于无代码的 Skill）：
 
 ````markdown
+
 ## 研究综合工作流
 
 复制此清单并跟踪进度：
 
 ```
 Research Progress:
-- [ ] Step 1: Read all source documents
-- [ ] Step 2: Identify key themes
-- [ ] Step 3: Cross-reference claims
-- [ ] Step 4: Create structured summary
-- [ ] Step 5: Verify citations
+
+* [ ] Step 1: Read all source documents
+
+* [ ] Step 2: Identify key themes
+
+* [ ] Step 3: Cross-reference claims
+
+* [ ] Step 4: Create structured summary
+
+* [ ] Step 5: Verify citations
 ```
 
 **Step 1: Read all source documents**
@@ -411,9 +462,12 @@ For each major claim, verify it appears in the source material. Note which sourc
 **Step 4: Create structured summary**
 
 Organize findings by theme. Include:
-- Main claim
-- Supporting evidence from sources
-- Conflicting viewpoints (if any)
+
+* Main claim
+
+* Supporting evidence from sources
+
+* Conflicting viewpoints (if any)
 
 **Step 5: Verify citations**
 
@@ -423,17 +477,23 @@ Check that every claim references the correct source document. If citations are
 **示例 2：PDF 表单填写工作流**（适用于有代码的 Skill）：
 
 ````markdown
+
 ## PDF form filling workflow
 
 Copy this checklist and check off items as you complete them:
 
 ```
 Task Progress:
-- [ ] Step 1: Analyze the form (run analyze_form.py)
-- [ ] Step 2: Create field mapping (edit fields.json)
-- [ ] Step 3: Validate mapping (run validate_fields.py)
-- [ ] Step 4: Fill the form (run fill_form.py)
-- [ ] Step 5: Verify output (run verify_output.py)
+
+* [ ] Step 1: Analyze the form (run analyze_form.py)
+
+* [ ] Step 2: Create field mapping (edit fields.json)
+
+* [ ] Step 3: Validate mapping (run validate_fields.py)
+
+* [ ] Step 4: Fill the form (run fill_form.py)
+
+* [ ] Step 5: Verify output (run verify_output.py)
 ```
 
 **Step 1: Analyze the form**
@@ -472,6 +532,7 @@ If verification fails, return to Step 2.
 **示例 1：风格指南合规**（适用于无代码的 Skill）：
 
 ```markdown
+
 ## Content review process
 
 1. Draft your content following the guidelines in STYLE_GUIDE.md
@@ -479,17 +540,18 @@ If verification fails, return to Step 2.
    - Check terminology consistency
    - Verify examples follow the standard format
    - Confirm all required sections are present
-3. If issues found:
+1. If issues found:
    - Note each issue with specific section reference
    - Revise the content
    - Review the checklist again
-4. Only proceed when all requirements are met
-5. Finalize and save the document
+1. Only proceed when all requirements are met
+2. Finalize and save the document
 ```
 
 **示例 2：文档编辑流程**（适用于有代码的 Skill）：
 
 ```markdown
+
 ## Document editing process
 
 1. Make your edits to `word/document.xml`
@@ -498,9 +560,9 @@ If verification fails, return to Step 2.
    - Review the error message carefully
    - Fix the issues in the XML
    - Run validation again
-4. **Only proceed when validation passes**
-5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
-6. Test the output document
+1. **Only proceed when validation passes**
+2. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
+3. Test the output document
 ```
 
 验证循环能早期捕获错误。
@@ -521,6 +583,7 @@ After August 2025, use the new API.
 **好示例**（使用"旧模式"部分）：
 
 ```markdown
+
 ## Current method
 
 Use the v2 API endpoint: `api.example.com/v2/messages`
@@ -545,13 +608,17 @@ This endpoint is no longer supported.
 **好——一致**：
 
 * 始终使用 "API endpoint"
+
 * 始终使用 "field"
+
 * 始终使用 "extract"
 
 **坏——不一致**：
 
 * 混用 "API endpoint"、"URL"、"API route"、"path"
+
 * 混用 "field"、"box"、"element"、"control"
+
 * 混用 "extract"、"pull"、"get"、"retrieve"
 
 一致性帮助 Claude 理解和遵循指令。
@@ -565,22 +632,29 @@ This endpoint is no longer supported.
 **对于严格要求**（如 API 响应或数据格式）：
 
 ````markdown
+
 ## Report structure
 
 ALWAYS use this exact template structure:
 
 ```markdown
+
 # [Analysis Title]
 
 ## Executive summary
+
 [One-paragraph overview of key findings]
 
 ## Key findings
-- Finding 1 with supporting data
-- Finding 2 with supporting data
-- Finding 3 with supporting data
+
+* Finding 1 with supporting data
+
+* Finding 2 with supporting data
+
+* Finding 3 with supporting data
 
 ## Recommendations
+
 1. Specific actionable recommendation
 2. Specific actionable recommendation
 ```
@@ -589,20 +663,25 @@ ALWAYS use this exact template structure:
 **对于灵活指导**（当适应有用时）：
 
 ````markdown
+
 ## Report structure
 
 Here is a sensible default format, but use your best judgment based on the analysis:
 
 ```markdown
+
 # [Analysis Title]
 
 ## Executive summary
+
 [Overview]
 
 ## Key findings
+
 [Adapt sections based on what you discover]
 
 ## Recommendations
+
 [Tailor to the specific context]
 ```
 
@@ -614,6 +693,7 @@ Adjust sections as needed for the specific analysis type.
 对于输出质量依赖于看到示例的 Skill，提供输入/输出对，就像在常规提示中一样：
 
 ````markdown
+
 ## Commit message format
 
 Generate commit messages following these examples:
@@ -646,6 +726,7 @@ Follow this style: type(scope): brief description, then detailed explanation.
 引导 Claude 通过决策点：
 
 ```markdown
+
 ## Document modification workflow
 
 1. Determine the modification type:
@@ -653,12 +734,12 @@ Follow this style: type(scope): brief description, then detailed explanation.
    **Creating new content?** → Follow "Creation workflow" below
    **Editing existing content?** → Follow "Editing workflow" below
 
-2. Creation workflow:
+1. Creation workflow:
    - Use docx-js library
    - Build document from scratch
    - Export to .docx format
 
-3. Editing workflow:
+1. Editing workflow:
    - Unpack existing document
    - Modify XML directly
    - Validate after each change
@@ -706,25 +787,28 @@ Follow this style: type(scope): brief description, then detailed explanation.
 
 1. **在没有 Skill 的情况下完成任务**：与 Claude A 通过正常提示解决问题。在工作过程中，你会自然地提供上下文、解释偏好并分享程序性知识。注意你反复提供的信息。
 
-2. **识别可复用模式**：完成任务后，识别你提供的哪些上下文对类似的未来任务有用。
+1. **识别可复用模式**：完成任务后，识别你提供的哪些上下文对类似的未来任务有用。
 
-3. **请 Claude A 创建 Skill**："创建一个捕获我们刚刚使用的 BigQuery 分析模式的 Skill。包括表 schema、命名约定以及关于过滤测试账户的规则。"
+1. **请 Claude A 创建 Skill**："创建一个捕获我们刚刚使用的 BigQuery 分析模式的 Skill。包括表 schema、命名约定以及关于过滤测试账户的规则。"
 
-4. **检查简洁性**：检查 Claude A 是否添加了不必要的解释。问："删除关于什么是胜率的解释——Claude 已经知道了。"
+1. **检查简洁性**：检查 Claude A 是否添加了不必要的解释。问："删除关于什么是胜率的解释——Claude 已经知道了。"
 
-5. **改进信息架构**：请 Claude A 更有效地组织内容。例如："将表 schema 组织到单独的参考文件中。我们以后可能会添加更多表。"
+1. **改进信息架构**：请 Claude A 更有效地组织内容。例如："将表 schema 组织到单独的参考文件中。我们以后可能会添加更多表。"
 
-6. **在类似任务上测试**：使用 Claude B（加载了 Skill 的新实例）在相关用例上使用 Skill。观察 Claude B 是否找到正确信息、正确应用规则并成功处理任务。
+1. **在类似任务上测试**：使用 Claude B（加载了 Skill 的新实例）在相关用例上使用 Skill。观察 Claude B 是否找到正确信息、正确应用规则并成功处理任务。
 
-7. **根据观察迭代**：如果 Claude B 遇到困难或遗漏了某些内容，带着具体情况返回 Claude A："当 Claude 使用此 Skill 时，它忘记按 Q4 日期过滤。我们应该添加关于日期过滤模式的部分吗？"
+1. **根据观察迭代**：如果 Claude B 遇到困难或遗漏了某些内容，带着具体情况返回 Claude A："当 Claude 使用此 Skill 时，它忘记按 Q4 日期过滤。我们应该添加关于日期过滤模式的部分吗？"
 
 ### 观察 Claude 如何导航 Skill
 
 在迭代 Skill 时，注意 Claude 在实践中实际如何使用它们。注意：
 
 * **意外的探索路径**：Claude 是否以你未预期的顺序读取文件？这可能表明你的结构不如你想象的直观
+
 * **错过的连接**：Claude 是否未能跟随对重要文件的引用？你的链接可能需要更明确或更突出
+
 * **对某些部分的过度依赖**：如果 Claude 反复读取同一文件，考虑该内容是否应该在主 SKILL.md 中
+
 * **被忽略的内容**：如果 Claude 从不访问某个捆绑文件，它可能是不必要的或在主指令中信号不足
 
 根据这些观察而非假设进行迭代。Skill 元数据中的 `name` 和 `description` 尤为关键。Claude 在决定是否触发 Skill 以响应当前任务时使用这些。确保它们清楚地描述 Skill 的功能和使用时机。
@@ -736,6 +820,7 @@ Follow this style: type(scope): brief description, then detailed explanation.
 在文件路径中始终使用正斜杠，即使在 Windows 上：
 
 * ✓ **好**：`scripts/helper.py`、`reference/guide.md`
+
 * ✗ **避免**：`scripts\helper.py`、`reference\guide.md`
 
 Unix 风格路径在所有平台上都有效，而 Windows 风格路径在 Unix 系统上会导致错误。
@@ -798,12 +883,17 @@ def process_file(path):
 **好示例：自文档化**：
 
 ```python
+
 # HTTP requests typically complete within 30 seconds
+
 # Longer timeout accounts for slow connections
+
 REQUEST_TIMEOUT = 30
 
 # Three retries balances reliability vs speed
+
 # Most intermittent failures resolve by the second retry
+
 MAX_RETRIES = 3
 ```
 
@@ -821,13 +911,17 @@ RETRIES = 5   # Why 5?
 **工具脚本的好处**：
 
 * 比生成的代码更可靠
+
 * 节省 token（无需在上下文中包含代码）
+
 * 节省时间（无需代码生成）
+
 * 确保跨使用的一致性
 
 **重要区别**：在指令中明确 Claude 是否应该：
 
 * **执行脚本**（最常见）："Run `analyze_form.py` to extract fields"
+
 * **作为参考读取**（对于复杂逻辑）："See `analyze_form.py` for the field extraction algorithm"
 
 对于大多数工具脚本，执行是首选，因为它更可靠和高效。
@@ -837,6 +931,7 @@ RETRIES = 5   # Why 5?
 当输入可以渲染为图像时，让 Claude 分析它们：
 
 ````markdown
+
 ## Form layout analysis
 
 1. Convert PDF to images:
@@ -844,8 +939,8 @@ RETRIES = 5   # Why 5?
    python scripts/pdf_to_images.py form.pdf
    ```
 
-2. Analyze each page image to identify form fields
-3. Claude can see field locations and types visually
+1. Analyze each page image to identify form fields
+2. Claude can see field locations and types visually
 ````
 
 Claude 的视觉能力有助于理解布局和结构。
@@ -857,8 +952,11 @@ Claude 的视觉能力有助于理解布局和结构。
 **为何此模式有效：**
 
 * **早期捕获错误**：验证在应用更改之前发现问题
+
 * **机器可验证**：脚本提供客观验证
+
 * **可逆规划**：Claude 可以在不触及原件的情况下迭代计划
+
 * **清晰调试**：错误消息指向具体问题
 
 **使用时机**：批量操作、破坏性更改、复杂验证规则、高风险操作。
@@ -868,6 +966,7 @@ Claude 的视觉能力有助于理解布局和结构。
 Skill 在具有平台特定限制的代码执行环境中运行：
 
 * **claude.ai**：可以从 npm 和 PyPI 安装包，并从 GitHub 仓库拉取
+
 * **Anthropic API**：没有网络访问，没有运行时包安装
 
 在 SKILL.md 中列出所需包，并验证它们在[代码执行工具文档](/en/docs/agents-and-tools/tool-use/code-execution-tool)中可用。
@@ -910,30 +1009,49 @@ reader = PdfReader("file.pdf")
 ### 核心质量
 
 * [ ] 描述具体且包含关键词
+
 * [ ] 描述包括 Skill 的功能和使用时机
+
 * [ ] SKILL.md 正文在 500 行以内
+
 * [ ] 额外细节在单独文件中（如需要）
+
 * [ ] 无时间敏感信息（或在"旧模式"部分）
+
 * [ ] 整个 Skill 使用一致的术语
+
 * [ ] 示例具体而非抽象
+
 * [ ] 文件引用只有一层深
+
 * [ ] 适当使用渐进式披露
+
 * [ ] 工作流有清晰步骤
 
 ### 代码和脚本
 
 * [ ] 脚本解决问题而非推卸给 Claude
+
 * [ ] 错误处理明确且有帮助
+
 * [ ] 无"魔法常量"（所有值都有理由）
+
 * [ ] 所需包在指令中列出并验证可用
+
 * [ ] 脚本有清晰文档
+
 * [ ] 无 Windows 风格路径（全部正斜杠）
+
 * [ ] 关键操作包含验证/核实步骤
+
 * [ ] 质量关键任务包含反馈循环
 
 ### 测试
 
 * [ ] 至少创建了三个评估
+
 * [ ] 使用 Haiku、Sonnet 和 Opus 测试
+
 * [ ] 使用真实使用场景测试
+
 * [ ] 已纳入团队反馈（如适用）

package/skills/writing-skills/examples/AGENTS.md

@@ -4,23 +4,27 @@
 # skills/writing-skills/examples/
 
 ## Purpose
+
 Writing Skills 示例目录。包含 skill 编写的示例文件，展示如何测试和验证 skill 定义，供 skill 开发者参考。
 
 ## Key Files
 
 | File | Description |
-|------|-------------|
+| ------ | ------------- |
 | `CLAUDE_MD_TESTING.md` | CLAUDE.md 测试示例，展示如何验证 skill 在 Claude Code 中的行为 |
 
 ## For AI Agents
 
 ### 修改此目录时
-- 参见 `skills/writing-skills/SKILL.md` 了解 skill 编写规范
-- 新增示例时确保覆盖不同类型的 skill 测试场景
+
+* 参见 `skills/writing-skills/SKILL.md` 了解 skill 编写规范
+
+* 新增示例时确保覆盖不同类型的 skill 测试场景
 
 ## Dependencies
 
 ### Internal
-- `skills/writing-skills/` — 父级 writing-skills skill
+
+* `skills/writing-skills/` — 父级 writing-skills skill
 
 <!-- MANUAL: -->