@tinkcarlos/skillora 0.2.0

package/.claude/skills/skill-expert-skills/references/patterns.md

@@ -0,0 +1,218 @@
+# Skill 模式库 (Patterns)
+
+本文档整合了工作流模式和输出模式，帮助设计高质量的 Skill。
+
+## 目录
+
+- [1. 工作流模式](#1-工作流模式-workflow-patterns)
+  - [1.1 顺序工作流](#11-顺序工作流-sequential-workflows)
+  - [1.2 条件工作流](#12-条件工作流-conditional-workflows)
+  - [1.3 反馈循环工作流](#13-反馈循环工作流-feedback-loop)
+- [2. 输出模式](#2-输出模式-output-patterns)
+  - [2.1 模板模式](#21-模板模式-template-pattern)
+  - [2.2 示例模式](#22-示例模式-examples-pattern)
+- [3. 测试与评估模式](#3-测试与评估模式-testing-patterns)
+  - [3.1 多模型测试](#31-多模型测试-multi-model-testing)
+  - [3.2 评估驱动开发](#32-评估驱动开发-evaluation-driven-development)
+
+---
+
+## 1. 工作流模式 (Workflow Patterns)
+
+### 1.1 顺序工作流 (Sequential Workflows)
+
+对于复杂的任务，将操作分解为清晰的顺序步骤。在 SKILL.md 的开头向 Claude 提供流程概览通常很有帮助：
+
+```markdown
+填充 PDF 表单涉及以下步骤：
+
+1. 分析表单 (运行 analyze_form.py)
+2. 创建字段映射 (编辑 fields.json)
+3. 校验映射 (运行 validate_fields.py)
+4. 填充表单 (运行 fill_form.py)
+5. 验证输出 (运行 verify_output.py)
+```
+
+### 1.2 条件工作流 (Conditional Workflows)
+
+对于具有分支逻辑的任务，引导 Claude 经过决策点：
+
+```markdown
+1. 确定修改类型：
+   **创建新内容？** → 遵循下方的"创建工作流"
+   **编辑现有内容？** → 遵循下方的"编辑工作流"
+
+2. 创建工作流：[步骤]
+3. 编辑工作流：[步骤]
+```
+
+### 1.3 反馈循环工作流 (Feedback Loop)
+
+**官方强调**：`运行验证器 → 修复错误 → 重复` 是提高输出质量的关键模式。
+
+```markdown
+## 验证循环（强制）
+
+1. 运行验证脚本
+2. 如有错误 → 修复 → 返回步骤 1
+3. 全部通过 → 完成
+
+示例：
+┌─────────────────────────────────────────┐
+│  运行 quick_validate.py                  │
+│       ↓                                  │
+│  通过? ─── 是 ──→ 运行 universal_validate │
+│       │                    ↓             │
+│       否                通过? ─── 是 ──→ ✅ 完成
+│       ↓                    │             │
+│  修复问题                  否             │
+│       ↓                    ↓             │
+│  返回步骤 1            修复问题           │
+│                            ↓             │
+│                       返回步骤 2          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 2. 输出模式 (Output Patterns)
+
+当 Skill 需要产生一致且高质量的输出时，请使用这些模式。
+
+### 2.1 模板模式 (Template Pattern)
+
+为输出格式提供模板。根据需求匹配严格程度。
+
+**对于严格要求（如 API 响应或数据格式）：**
+
+```markdown
+## 报告结构
+
+务必使用此精确的模板结构：
+
+# [分析标题]
+
+## 执行摘要
+[对关键发现的一段概述]
+
+## 关键发现
+- 发现 1 以及支持数据
+- 发现 2 以及支持数据
+- 发现 3 以及支持数据
+
+## 建议
+1. 具体且可操作的建议
+2. 具体且可操作的建议
+```
+
+**对于灵活指导（当需要适配时）：**
+
+```markdown
+## 报告结构
+
+这是一个合理的默认格式，但请根据你的判断进行调整：
+
+# [分析标题]
+
+## 执行摘要
+[概述]
+
+## 关键发现
+[根据你的发现适配各个章节]
+
+## 建议
+[根据具体语境量身定制]
+
+根据具体的分析类型，按需调整章节。
+```
+
+### 2.2 示例模式 (Examples Pattern)
+
+对于输出质量依赖于参考示例的 Skill，请提供输入/输出对：
+
+```markdown
+## Commit 消息格式
+
+参考这些示例生成 commit 消息：
+
+**示例 1:**
+输入: Added user authentication with JWT tokens
+输出:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**示例 2:**
+输入: Fixed bug where dates displayed incorrectly in reports
+输出:
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+```
+
+遵循此风格：类型(范围): 简短描述，然后是详细说明。
+```
+
+相比于单纯的文字描述，示例能更清晰地帮助 Claude 理解所需的风格和详细程度。
+
+---
+
+## 3. 测试与评估模式 (Testing Patterns)
+
+### 3.1 多模型测试 (Multi-Model Testing)
+
+**官方建议**：在不同模型上测试 Skill，确保指令足够清晰。
+
+**测试矩阵**：
+
+| 模型 | 用途 | 测试重点 |
+|------|------|----------|
+| Haiku | 快速/低成本任务 | 指令是否足够明确？ |
+| Sonnet | 平衡性能/成本 | 主要功能是否正常？ |
+| Opus | 复杂推理任务 | 边缘情况处理如何？ |
+
+**测试流程**：
+```
+1. 准备 3-5 个代表性测试用例
+2. 在 Haiku 上运行 → 如果失败，说明指令不够清晰
+3. 在 Sonnet 上运行 → 验证主要功能
+4. 在 Opus 上运行 → 验证复杂场景
+5. 记录各模型表现差异，优化指令
+```
+
+**关键原则**：
+- 如果 Haiku 无法正确执行，说明 Skill 指令需要更明确
+- 不要依赖模型的"聪明"来弥补指令的模糊
+
+### 3.2 评估驱动开发 (Evaluation-Driven Development)
+
+**核心理念**：像测试驱动开发一样，先定义成功标准，再编写 Skill。
+
+**评估清单模板**：
+```markdown
+## 评估标准
+
+### 功能性 (必须通过)
+- [ ] 触发词正确激活 Skill
+- [ ] 核心流程可执行
+- [ ] 输出格式符合预期
+
+### 鲁棒性 (应该通过)
+- [ ] 边缘输入处理得当
+- [ ] 错误情况有明确提示
+- [ ] 不同模型表现一致
+
+### 效率 (可选优化)
+- [ ] Token 使用合理
+- [ ] 无冗余步骤
+- [ ] 渐进式披露有效
+```
+
+**迭代改进循环**：
+```
+定义评估标准 → 编写 Skill → 运行测试 → 分析失败 → 改进 Skill → 重复
+```
+

package/.claude/skills/skill-expert-skills/references/plugin-skills-guide.md

@@ -0,0 +1,432 @@
+# Claude Code 插件 Skill 开发指南
+
+本文档提供为 Claude Code 插件创建 Skill 的专门指导。
+
+---
+
+## 插件 Skill vs 普通 Skill
+
+| 维度 | 普通 Skill | 插件 Skill |
+|------|------------|------------|
+| **位置** | `$HOME/.claude/skills/` 或 `.claude/skills/` | `plugin-name/skills/` |
+| **分发** | 手动复制或 .skill 包 | 随插件一起安装 |
+| **打包** | 需要 package_skill.py | 不需要单独打包 |
+| **发现** | Claude 全局扫描 | 插件加载时扫描 |
+| **依赖** | 独立 | 可依赖插件其他组件 |
+
+---
+
+## 插件目录结构
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # 插件元数据
+├── commands/                 # 斜杠命令
+├── agents/                   # 自定义 Agent
+└── skills/                   # 插件 Skills
+    ├── skill-a/
+    │   ├── SKILL.md
+    │   ├── references/
+    │   ├── examples/
+    │   └── scripts/
+    └── skill-b/
+        └── SKILL.md
+```
+
+---
+
+## 创建插件 Skill 流程
+
+### Step 1: 初始化目录
+
+```bash
+# 在插件根目录下创建
+mkdir -p skills/my-skill/{references,examples,scripts}
+touch skills/my-skill/SKILL.md
+```
+
+### Step 2: 编写 SKILL.md
+
+```yaml
+---
+name: my-skill
+description: |
+  This skill should be used when the user asks to "specific action 1",
+  "specific action 2", or mentions relevant keywords.
+
+  Provides [capability] within the [plugin-name] plugin context.
+---
+```
+
+### Step 3: 添加支持文件
+
+根据需要添加:
+- `references/` - 详细文档
+- `examples/` - 工作示例
+- `scripts/` - 工具脚本
+
+### Step 4: 测试
+
+```bash
+# 使用插件目录测试
+claude --plugin-dir /path/to/my-plugin
+
+# 询问触发问题
+> "help me with [trigger phrase]"
+```
+
+---
+
+## 插件 Skill 自动发现机制
+
+Claude Code 按以下顺序加载 Skill:
+
+```
+1. 扫描 skills/ 目录
+2. 查找包含 SKILL.md 的子目录
+3. 解析 frontmatter (name + description)
+4. 将 metadata 加载到上下文 (~100 words)
+5. 当 Skill 触发时，加载 SKILL.md body (<5k words)
+6. 按需加载 references/examples/scripts
+```
+
+### 发现要求
+
+- [ ] 目录在 `skills/` 下
+- [ ] 包含 `SKILL.md` 文件
+- [ ] SKILL.md 有有效的 YAML frontmatter
+- [ ] frontmatter 包含 `name` 和 `description`
+
+---
+
+## 渐进式披露设计
+
+### 三层加载系统
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ 层级                         │ 加载时机        │ 大小限制           │
+├──────────────────────────────┼────────────────┼───────────────────┤
+│ Layer 1: Metadata            │ 始终加载        │ ~100 words        │
+│ (name + description)         │                │                    │
+├──────────────────────────────┼────────────────┼───────────────────┤
+│ Layer 2: SKILL.md body       │ Skill 触发时   │ 1,500-2,000 words │
+│ (核心指令和流程)              │                │ (max 5,000)       │
+├──────────────────────────────┼────────────────┼───────────────────┤
+│ Layer 3: Bundled Resources   │ 按需加载        │ 无限制*           │
+│ (references/examples/scripts)│                │                    │
+└─────────────────────────────────────────────────────────────────────┘
+
+* scripts 可执行而不加载到上下文
+```
+
+### 内容分配指南
+
+**放入 SKILL.md (始终加载)**:
+- 核心概念和流程概览
+- 快速参考表
+- 指向 references 的导航
+- 最常见用例
+
+**放入 references/ (按需加载)**:
+- 详细模式和高级技术
+- 完整 API 文档
+- 迁移指南
+- 边缘案例处理
+- 扩展示例
+
+**放入 examples/ (按需加载)**:
+- 完整可运行脚本
+- 配置文件示例
+- 模板文件
+
+**放入 scripts/ (可执行)**:
+- 验证工具
+- 自动化脚本
+- 解析工具
+
+---
+
+## 插件 Skill 最佳实践
+
+### 1. 保持 SKILL.md 精炼
+
+```markdown
+# 目标: 1,500-2,000 words
+
+# ✅ 好的结构
+## Overview (200 words)
+## Quick Reference Table (300 words)
+## Core Workflow (500 words)
+## Output Contract (200 words)
+## References Navigation (100 words)
+
+# ❌ 避免
+## 8,000 words of detailed documentation all in SKILL.md
+```
+
+### 2. 强触发 Description
+
+```yaml
+# ✅ 好的 description
+description: |
+  This skill should be used when the user asks to "create a hook",
+  "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
+  or mentions hook events (PreToolUse, PostToolUse, Stop).
+
+  Provides comprehensive hooks API guidance for the plugin-dev plugin.
+
+# ❌ 差的 description
+description: |
+  Provides hook guidance.
+```
+
+### 3. 引用支持文件
+
+```markdown
+# 在 SKILL.md 中明确引用
+
+## Additional Resources
+
+### Reference Files
+- **`references/patterns.md`** - Detailed hook patterns
+- **`references/advanced.md`** - Advanced techniques
+
+### Examples
+- **`examples/pre-tool-hook.sh`** - PreToolUse example
+- **`examples/validation-hook.py`** - Validation example
+
+### Scripts
+- **`scripts/validate-hook.sh`** - Hook validation utility
+```
+
+### 4. 写作风格一致性
+
+```markdown
+# ✅ 正确: 祈使句
+Configure the hook by editing hooks.json.
+Validate the configuration with scripts/validate.sh.
+
+# ❌ 错误: 第二人称
+You should configure the hook by editing hooks.json.
+You can validate the configuration with scripts/validate.sh.
+```
+
+---
+
+## 插件 Skill 模板
+
+### 完整模板
+
+```markdown
+---
+name: my-plugin-skill
+description: |
+  This skill should be used when the user asks to "action 1",
+  "action 2", "action 3", or mentions relevant keywords.
+
+  Provides [capability] within the [plugin-name] plugin context.
+---
+
+# My Plugin Skill
+
+## Overview
+
+Brief description of what this skill provides within the plugin.
+
+## Quick Reference
+
+| Task | Command/Action |
+|------|----------------|
+| Task 1 | `command` |
+| Task 2 | `command` |
+
+## Core Workflow
+
+### Step 1: Preparation
+
+Describe preparation steps using imperative form.
+
+### Step 2: Implementation
+
+Describe implementation steps.
+
+### Step 3: Validation
+
+Describe validation steps.
+
+```bash
+# Validation command
+scripts/validate.sh
+```
+
+## Output Contract
+
+### Expected Deliverables
+- Deliverable 1
+- Deliverable 2
+
+### Quality Criteria
+- Criterion 1
+- Criterion 2
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Issue 1 | Solution 1 |
+| Issue 2 | Solution 2 |
+
+## Additional Resources
+
+### Reference Files
+- **`references/patterns.md`** - Detailed patterns
+- **`references/advanced.md`** - Advanced techniques
+
+### Examples
+- **`examples/example.sh`** - Working example
+```
+
+---
+
+## 测试插件 Skill
+
+### 本地测试
+
+```bash
+# 方式 1: 使用 --plugin-dir
+claude --plugin-dir /path/to/my-plugin
+
+# 方式 2: 符号链接到插件目录
+ln -s /path/to/.../my-plugin $HOME/.claude/plugins/my-plugin
+```
+
+### 测试清单
+
+- [ ] Skill 在 `/skills` 命令中显示
+- [ ] 触发短语正确激活 Skill
+- [ ] 指令被正确遵循
+- [ ] references 按需加载
+- [ ] scripts 可执行
+- [ ] examples 完整可用
+
+### 调试
+
+```bash
+# 启用调试模式
+claude --debug --plugin-dir /path/to/my-plugin
+
+# 检查加载日志
+# 查看 Skill 发现和激活信息
+```
+
+---
+
+## 与插件其他组件集成
+
+### 与 Commands 集成
+
+```markdown
+# 在 SKILL.md 中引用命令
+
+## Quick Start
+
+Run the `/my-command` slash command to get started.
+
+Or use the skill directly by asking about [topic].
+```
+
+### 与 Agents 集成
+
+```markdown
+# 在 SKILL.md 中引用 Agent
+
+## Advanced Usage
+
+For complex tasks, use the `my-agent` agent:
+
+```
+Ask: "Use my-agent to handle this"
+```
+```
+
+### 共享资源
+
+```
+my-plugin/
+├── shared/                   # 共享资源
+│   └── schemas/
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md          # 可引用 ../../shared/
+└── agents/
+```
+
+---
+
+## 常见问题
+
+### Q: 插件 Skill 需要打包吗?
+
+不需要。插件 Skill 随插件一起分发，用户安装插件时自动获得所有 Skill。
+
+### Q: 如何处理依赖?
+
+在 SKILL.md 中文档化依赖，或在 `scripts/requirements.txt` 中列出:
+
+```markdown
+## Prerequisites
+
+```bash
+pip install -r skills/my-skill/scripts/requirements.txt
+```
+```
+
+### Q: Skill 可以调用插件的其他功能吗?
+
+可以。在 SKILL.md 中引用:
+- 其他 Skill: "See the `other-skill` skill for..."
+- 命令: "Run `/command` to..."
+- Agent: "Use the `agent-name` agent for..."
+
+### Q: 如何处理版本兼容性?
+
+在 description 或 SKILL.md 中注明:
+
+```yaml
+description: |
+  ...
+  Requires: plugin-dev v2.0+
+```
+
+---
+
+## 检查清单
+
+### 结构检查
+
+- [ ] Skill 在 `skills/` 目录下
+- [ ] 包含 `SKILL.md`
+- [ ] 目录名与 frontmatter `name` 匹配
+
+### Frontmatter 检查
+
+- [ ] 有 `name` 字段
+- [ ] 有 `description` 字段
+- [ ] description 使用第三人称
+- [ ] description 包含触发短语
+
+### 内容检查
+
+- [ ] SKILL.md < 3,000 words (推荐 < 2,000)
+- [ ] 使用祈使句写作
+- [ ] 详细内容在 references/
+- [ ] 明确引用支持文件
+
+### 测试检查
+
+- [ ] Skill 正确触发
+- [ ] 指令被遵循
+- [ ] scripts 可执行
+- [ ] examples 完整