Skills 仓库

这是一个结构化的技能文档仓库，用于存储和管理各类技术技能的详细指南和最佳实践。

📋 仓库说明

本仓库按照统一的规范存放多个 Skills（技能文档），每个 Skill 包含：

• SKILL.md: 技能的核心概念、快速入门和最佳实践（AI 优先读取）
• reference.md: 详细的代码示例和完整参考（按需查阅）

🎯 目标用户

• AI 助手: 快速理解和使用各类技术栈的最佳实践
• 开发者: 学习特定技术的规范、常见陷阱和解决方案
• 团队: 统一技术规范，提高代码质量

📁 目录结构

skills/
├── README.md                    # 本文件 - 仓库总览
├── {skill-name}/                # 技能目录
│   ├── SKILL.md                 # 技能核心文档（必需）
│   └── reference.md             # 详细参考文档（可选）
└── ...

现有 Skills

技能名称	描述	技术栈
easywechat	微信开发 SDK 使用指南，涵盖公众号、小程序、企业微信、微信支付等	EasyWeChat 6.x, Hyperf
hyperf-container	Hyperf 依赖注入容器使用指南，包括服务注册、依赖获取、自动注入等	Hyperf, PSR-11
hyperf-upgrade	Hyperf 框架版本升级指南，涵盖 3.0 到 3.2 的破坏性变更和迁移方案	Hyperf 3.x

📖 Skill 文档规范

每个 Skill 目录必须包含 SKILL.md 文件，遵循以下结构：

SKILL.md 标准结构

---
name: skill-name
description: 简短描述，说明此技能的用途和适用场景
---

# 技能标题

## 核心概念
- 技术简介
- 支持的平台/功能列表
- 版本说明和注意事项

## 安装配置
- 安装命令
- 必需组件（特别强调）
- 基础配置文件示例

## 快速开始
- 推荐的使用模式（如 Factory、Service）
- 单例模式实现（如需要）
- 在 Controller/Service 中的使用示例

## 最佳实践
### DO ✓
- 应该做的事情

### DON'T ✗
- 应该避免的事情

## 常见问题
1. 问题描述 + 解决方案
2. 问题描述 + 解决方案
...

## 完整示例参考
指向 reference.md 的链接

## 相关资源
- 官方文档链接
- 社区资源

reference.md 标准结构

# 详细参考

## ⚠️ 重要提示
- 版本兼容性说明
- 环境要求
- 关键注意事项

## 分类示例
### 场景 1: XXX
- 完整的代码示例
- 真实可用的实现
- 详细的注释说明

### 场景 2: YYY
...

## API 调用规范
- 标准调用流程
- 常用工具方法
- 参数构建示例

## 对比表格
不同实现方式的优缺点对比

## 重要提醒
- 版本差异说明
- 废弃方法警告
- 迁移指南

🔍 AI 读取指南

快速定位信息

AI 在需要使用某个 Skill 时，应按以下顺序读取：

1. 首先读取 SKILL.md

   • 查看 description 确认是否匹配需求
   • 阅读"核心概念"了解技术背景
   • 查看"安装配置"获取必需组件
   • 重点阅读"最佳实践"的 DO/DON'T
   • 查阅"常见问题"解决已知问题

2. 按需读取 reference.md

   • 查找具体场景的代码示例
   • 参考 API 调用方式
   • 了解完整的实现细节

3. 关注版本信息

   • 注意 SDK/库的版本号
   • 检查是否有破坏性变更
   • 确认协程/并发环境的特殊要求

关键信息提取

AI 应特别注意以下内容：

✅ 必须遵守的规范

• 实例管理模式（单例/多例）
• 必需的适配组件
• 安全要求（验签、加密等）

✅ 版本特定的变化

• API 方法的增减
• 调用方式的改变
• 废弃功能的替代方案

✅ 环境适配要求

• 协程环境的特殊处理
• 缓存策略的选择
• 并发问题的解决方案

🛠️ 添加新 Skill

如需添加新的 Skill，请遵循以下步骤：

1. 创建目录

   mkdir {skill-name}

2. 创建 SKILL.md

   • 填写 Front Matter（name 和 description）
   • 按照标准结构编写内容
   • 确保包含核心概念、安装配置、最佳实践

3. 创建 reference.md（可选）

   • 提供详细的代码示例
   • 覆盖常见使用场景
   • 标注版本差异

4. 更新本 README

   • 在"现有 Skills"表格中添加新技能
   • 简要描述其用途和技术栈

5. 提交代码

   git add .
   git commit -m "docs: add {skill-name} skill"
   git push

📝 编写原则

内容质量

• ✅ 准确性: 所有代码示例必须经过验证，确保可运行
• ✅ 完整性: 覆盖核心功能和常见场景
• ✅ 时效性: 及时更新以反映最新版本的变化
• ✅ 实用性: 聚焦实际问题，提供可落地的解决方案

代码示例

• ✅ 使用真实的类名、方法名和参数
• ✅ 包含必要的 import/use 语句
• ✅ 添加关键注释说明重点
• ✅ 展示错误处理和边界情况

文档结构

• ✅ 层次清晰，便于快速定位
• ✅ 使用表格对比不同方案
• ✅ 重要信息使用警告框突出显示
• ✅ 提供相关链接便于深入阅读

🤝 贡献指南

欢迎贡献新的 Skills 或改进现有文档！

贡献流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-skill)
3. 提交更改 (git commit -m 'Add amazing skill')
4. 推送到分支 (git push origin feature/amazing-skill)
5. 提交 Pull Request

审查要点

• 代码示例是否可运行
• 是否符合当前版本
• 是否覆盖了关键场景
• 文档结构是否清晰
• 是否有拼写或语法错误

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🔗 相关链接

• Hyperf 官方文档
• EasyWeChat 官方文档
• PSR-11 容器规范

---

维护者: Hyperf Community
最后更新: 2026-04-27