1k-new-skill

创建新技能

创建新的 Claude Code 技能时，请遵循此工作流。

0) 获取最新最佳实践（必需）

在编写任何技能内容之前，必须获取并阅读最新文档：

1. 技能概览：https://code.claude.com/docs/en/skills
2. 最佳实践：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

使用 WebFetch 检索这些页面，并在继续之前提取关键指南。

1) 检查技能是否应合并到现有技能中（必需）

创建新技能之前，请先检查内容是否属于现有技能。

查看现有技能

ls -la .claude/skills/

合并决策标准

符合以下任一条件时，原则上应合并到现有技能中：

• 主题与现有技能的领域密切相关
• 内容属于现有技能的子主题
• 已存在类似的工作流或模式
• 将其作为规则添加可以让相关知识保持集中

符合以下任一条件时，创建新技能：

• 主题独立且不属于任何现有类别
• 内容足够丰富，值得设立独立技能
• 触发关键词和使用场景不同
• 将其加入现有技能会使该技能过于庞大或失去重点

Token 优化注意事项

何时拆分现有技能：

技能过于庞大时，应进行拆分，以免每次加载时消耗不必要的 token。可依据以下标准：

🚨 符合以下任一条件时，必须拆分：

• 文件大小：参考文件 >10 KB 或 >1000 行
• 使用频率不匹配：主题用于截然不同的场景
• 工作流独立：主题之间没有共同模式
• 特定触发词：主题有独特关键词，很少与其他主题重叠

✅ 符合以下条件时，保持在一起：

• 高度相关：主题经常一起使用（重叠度 >50%）
• 概念共享：具有共同的模式、术语或工作流
• 文件较小：所有参考文件均 <5 KB
• 自然归类：用户会将这些主题视为相关内容

Token 节省公式：

Token Savings = (Skill_Size × Probability_Not_Needed) - Split_Overhead

Where:
- Skill_Size: Total tokens in skill (SKILL.md + all references)
- Probability_Not_Needed: % of tasks that don't need this topic
- Split_Overhead: ~500-1000 tokens (new SKILL.md + metadata)

我们代码库中的实际示例：

原始内容	大小	拆分为	Token 节省
1k-coding-patterns	15 KB（9 个文件）	6 个专注型技能	90% 的情况下可节省 47-53%
1k-dev-workflows	43 KB（3 个文件）	3 个专注型技能	不处理 Sentry 时可节省 80%

拆分策略：

1. 保守拆分（安全、改动最少）：

   • 仅拆分最大的、最独立的文件
   • 保持相关主题在一起
   • 示例：从 43 KB 工作流中拆出 34 KB 的 Sentry 分析

2. 适度拆分（均衡）：

   • 将 3-5 个不同主题拆分为独立技能
   • 将核心模式保留在一起
   • 示例：拆分日期、i18n、错误处理、跨平台和代码质量

3. 激进拆分（最大限度优化）：

   • 每个主要主题都成为独立技能
   • 仅将真正不可分割的内容保留在一起
   • 适用于：技能非常庞大（>50 KB）、主题相关性较低

OneKey 现有的技能类别

类别	技能	合并候选项
分析/跟踪	1k-analytics	事件跟踪、Mixpanel、LogToServer、defaultLogger
架构	1k-architecture	项目结构、导入规则
代码质量	1k-code-quality	Lint 修复、提交前任务、文档
代码审查	1k-code-review-pr	PR 审查清单
编码模式	1k-coding-patterns	React 模式、TypeScript 规范
创建 PR	1k-create-pr	PR 创建工作流
跨平台	1k-cross-platform	平台专属代码
日期格式化	1k-date-formatting	日期/时间显示、本地化格式
DeFi 集成	1k-defi-module-integration	Staking、lending、Earn、Borrow 模块
开发命令	1k-dev-commands	构建、测试、lint 命令
错误处理	1k-error-handling	Try/catch、错误边界、面向用户的错误
功能开发	1k-feature-guides	新链、Socket 事件、通知、页面、路由
Git 工作流	1k-git-workflow	分支、提交、PR
集体思考	1k-group-think	多 Agent 协作分析
国际化	1k-i18n	翻译、本地化
监控 PR CI	1k-monitor-pr-ci	CI 检查监控、PR 状态
原生模块补丁	1k-patching-native-modules	iOS/Android 崩溃修复、原生代码补丁
软件包升级	1k-pkg-upgrade-review	依赖升级审查、兼容性
性能	1k-performance	优化、并发请求、记忆化
平台要求	1k-platform-requirements	所有平台的最低 SDK/OS 版本
回顾	1k-retrospective	Bug 修复分析、清单更新
Sentry 分析	1k-sentry-analysis	崩溃报告、AppHang、ANR 修复
Sentry 配置	1k-sentry	错误筛选、崩溃配置
状态管理	1k-state-management	Jotai atoms、全局状态
测试版本	1k-app-upgrade-test	应用自动更新测试、版本迁移
UI 配方	1k-ui-recipes	滚动偏移、视图过渡、键盘避让

合并工作流

如果合并到现有技能：

1. 添加为规则文件：

   .claude/skills/<existing-skill>/
   ├── SKILL.md                          # Update quick reference
   └── references/rules/
       └── <new-topic>.md                # Add detailed content here
   

2. 更新主 SKILL.md：

   • 在快速参考表中添加条目
   • 添加简要摘要部分
   • 链接到新规则文件

3. 合并示例：

   ## Quick Reference
   
   | Feature | Guide | Key Files |
   |---------|-------|-----------|
   | Existing topic | [existing.md](references/rules/existing.md) | `path/to/files` |
   | **New topic** | [new-topic.md](references/rules/new-topic.md) | `path/to/files` |  
   

拆分工作流

如果拆分现有技能：

1. 分析当前技能：

   # Check file sizes
   ls -lh .claude/skills/<skill-name>/references/rules/
   wc -l .claude/skills/<skill-name>/references/rules/*.md
   

2. 确定拆分候选项：

   • 文件超过 10 KB 或 1000 行
   • 具有不同触发词的主题
   • 可独立使用的工作流

3. 创建新的技能目录：

   mkdir -p .claude/skills/<new-skill-1>/references/rules
   mkdir -p .claude/skills/<new-skill-2>/references/rules
   

4. 移动文件（git 会跟踪为重命名）：

   mv .claude/skills/<old-skill>/references/rules/<topic>.md \
      .claude/skills/<new-skill>/references/rules/
   

5. 为每个新技能创建 SKILL.md：

   • 编写聚焦的描述，并指定触发词
   • 添加快速参考部分
   • 添加相关技能部分

6. 更新原技能的 SKILL.md：

   • 从快速参考中移除拆分出的主题
   • 更新相关技能，使其指向新技能

7. 更新交叉引用：

   # Find all skills that reference the old skill
   grep -r "old-skill" .claude/skills/*/SKILL.md
   
   # Update each reference to point to appropriate new skill
   

8. 使用清晰的消息提交：

   git add -A .claude/skills/
   git commit -m "refactor: split <old-skill> into focused skills"
   

2）收集需求（针对新技能）

如果要创建新技能，请询问用户：

• 这个技能应该自动化什么任务？
• 应由哪些触发条件激活此技能？（关键词、文件类型、上下文）
• 应限定于项目（.claude/skills/）还是个人使用（~/.claude/skills/）？
• 它需要哪些工具？（Read、Grep、Glob、Bash、WebFetch、Write 等）

3）创建技能结构

标准结构（推荐用于 OneKey 技能）

.claude/skills/1k-<skill-name>/
├── SKILL.md                    # Main entry with quick reference (required)
└── references/
    └── rules/
        ├── topic-1.md          # Detailed guide for topic 1
        ├── topic-2.md          # Detailed guide for topic 2
        └── topic-3.md          # Detailed guide for topic 3

简单结构（用于单主题技能）

.claude/skills/1k-<skill-name>/
└── SKILL.md                    # All content in one file

SKILL.md 模板

---
name: 1k-skill-name
description: Brief description of what this Skill does and when to use it. Include specific trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

# Skill Title

Brief overview.

## Quick Reference

| Topic | Guide | Key Files |
|-------|-------|-----------|
| Topic 1 | [topic-1.md](references/rules/topic-1.md) | `path/to/files` |
| Topic 2 | [topic-2.md](references/rules/topic-2.md) | `path/to/files` |

## Topic 1 Summary

See: [references/rules/topic-1.md](references/rules/topic-1.md)

**Key points:**
- Point 1
- Point 2

## Topic 2 Summary

See: [references/rules/topic-2.md](references/rules/topic-2.md)

**Key points:**
- Point 1
- Point 2

## Related Skills

- `/1k-related-skill-1` - Description
- `/1k-related-skill-2` - Description

4）应用最佳实践检查清单

命名

• 必需：所有 OneKey 项目的技能都使用 1k- 前缀
• 使用描述性名称：1k-feature-guides、1k-dev-workflows、1k-sentry
• 最长 64 个字符，仅限小写字母、数字和连字符
• 不使用保留词：“anthropic”、“claude”

描述

• 使用第三人称（“处理……”，而非“我可以帮忙……”）
• 说明它的功能以及适用场景
• 包含用户可能会说的具体触发关键词
• 最长 1024 个字符

内容结构

• 主 SKILL.md 包含指向规则的快速参考表
• 详细内容放在 references/rules/*.md 中
• 每个规则文件都应内容完整、重点明确
• SKILL.md 正文少于 500 行
• 使用 Unix 风格路径（正斜杠）

组织方式

• 将相关主题归入一个技能，并包含多条规则
• 所有规则使用一致的格式
• 添加“相关技能”部分以便交叉引用
• 为复杂工作流添加检查清单

5) 输出技能

收集需求并应用最佳实践后：

1. 创建包含 references/rules/ 结构的技能目录
2. 编写包含快速参考表的 SKILL.md
3. 为每个主题添加规则文件
4. 总结创建的内容
5. 运行令牌分析以验证优化效果（必需）

令牌分析（自检）

创建或修改技能后，始终运行：

# Run token analysis
python3 development/skills-analysis/analyze-skills-tokens.py --sort-by-size

# Check your new skill's token count
python3 development/skills-analysis/analyze-skills-tokens.py --detailed | grep -A 5 "your-skill-name"

验证清单：

• 新技能少于 5,000 个令牌（理想情况）
• 如果超过 5,000 个令牌：各主题的相关性较高（共同使用率 >50%）
• 如果超过 10,000 个令牌：立即规划拆分
• SKILL.md 包含快速参考（避免强制加载整个文件）
• 不同技能之间没有重复内容

根据结果采取行动：

令牌数	操作
< 2,000	✅ 极佳——继续
2,000 - 5,000	✅ 良好——继续，监控增长
5,000 - 10,000	⚠️ 检查：是否可以拆分主题？如果相关性较高，则使用快速参考继续
> 10,000	🚨 提交前拆分

详细指南请参阅 development/skills-analysis/SKILLS-TOKEN-MONITORING.md。

示例：包含多条规则的技能

.claude/skills/1k-feature-guides/
├── SKILL.md
└── references/rules/
    ├── adding-chains.md
    ├── adding-socket-events.md
    ├── notification-system.md
    └── page-and-route.md

SKILL.md 内容：

---
name: 1k-feature-guides
description: Feature development guides for OneKey. Use when adding new chains, socket events, notifications, pages, or routes.
---

# Feature Development Guides

## Quick Reference

| Feature | Guide | Key Files |
|---------|-------|-----------|
| Add blockchain chain | [adding-chains.md](references/rules/adding-chains.md) | `packages/core/src/chains/` |
| Add WebSocket events | [adding-socket-events.md](references/rules/adding-socket-events.md) | `packages/shared/types/socket.ts` |

## Adding New Chains

See: [references/rules/adding-chains.md](references/rules/adding-chains.md)

**Key steps:**
1. Implement chain core logic
2. Add chain configuration
3. Update UI components

应避免的反模式

结构与组织

• ❌ 内容适合现有类别时仍创建新技能
• ❌ 将所有内容都放进 SKILL.md（详细内容应使用 references/rules）
• ❌ 文件引用嵌套过深（保持一层深度）
• ❌ 忘记为 OneKey 技能添加 1k- 前缀

内容质量

• ❌ 使用“帮助处理文档”之类含糊的描述
• ❌ 提供多种方法，却没有明确的默认选项
• ❌ 过度解释 Claude 已经了解的内容
• ❌ 描述中缺少触发关键词

令牌优化反模式

• ❌ 保留臃肿的技能：文件超过 10 KB 时仍不拆分
• ❌ 过度拆分：为高度相关的主题创建独立技能
• ❌ 忽略使用模式：不考虑哪些主题会一起使用
• ❌ 触发词含糊：使用通用触发词，导致不必要的加载
• ❌ 没有快速参考：不先展示摘要，而是强制加载整个文件
• ❌ 内容重复：在不同技能之间复制内容，而不是交叉引用

拆分示例：好与坏

❌ 错误：过度拆分

1k-date-format-display
1k-date-format-parse
1k-date-format-locale

问题：这些内容总是一起使用，拆分带来的开销大于收益

✅ 正确：重点明确的技能

1k-date-formatting
├── SKILL.md (Quick Reference)
└── references/rules/date-formatting.md

❌ 错误：保留臃肿的技能

1k-coding-patterns (15 KB, 9 unrelated files)

问题：即使只需要一种模式，也会加载所有模式

✅ 正确：按独立性拆分

1k-coding-patterns (core patterns only)
1k-date-formatting (independent utility)
1k-i18n (independent utility)
1k-error-handling (independent patterns)