diff --git a/README.md b/README.md
index 015eb17..1ab3f57 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,94 @@
-# ieslab自建技能仓库
\ No newline at end of file
+# ieslab 自建技能仓库
+
+ieslab 团队的 Claude Code 自定义 Skills 集合，以插件形式统一管理和分发。
+
+## 目录结构
+
+```
+ieslab_skills/
+├── README.md
+└── skills/                    # 技能定义目录
+    └── <skill-name>/          # 每个技能独立子目录
+        ├── SKILL.md           # 技能主文件（必需）
+        └── ...                # 可选辅助文件（脚本、模板、参考文档等）
+```
+
+## 安装
+
+### 1. 克隆仓库
+
+```bash
+git clone <repo-url> /path/to/ieslab_skills
+```
+
+### 2. 启用插件
+
+在需要使用技能的项目中，编辑 `.claude/settings.json`，添加插件路径：
+
+```json
+{
+  "plugins": ["/path/to/ieslab_skills"]
+}
+```
+
+或在用户全局配置 `~/.claude/settings.json` 中添加，对所有项目生效。
+
+### 3. 验证安装
+
+在 Claude Code 中输入 `/`，可以在补全列表中看到已安装的技能。
+
+## 添加新技能
+
+每个技能存放在 `skills/<技能名>/` 目录下，至少包含一个 `SKILL.md` 文件。
+
+### SKILL.md 格式
+
+```yaml
+---
+name: skill-name           # 技能名，默认取目录名
+description: 技能描述       # 建议填写，Claude 会根据此字段自动判断是否加载
+argument-hint: "[参数]"    # 可选，调用时显示的参数提示
+---
+
+技能的详细指令内容...
+```
+
+### 常用可选字段
+
+| 字段 | 说明 |
+|------|------|
+| `disable-model-invocation: true` | 禁止 Claude 自动调用，仅允许手动 `/` 调用 |
+| `user-invocable: false` | 仅允许 Claude 自动调用，不在 `/` 菜单中显示 |
+| `allowed-tools: Read, Grep` | 限制此技能可使用的工具 |
+| `model: claude-opus-4-6` | 指定运行此技能的模型 |
+| `context: fork` | 在子 Agent 中独立运行 |
+
+### 目录规范
+
+```
+skills/my-skill/
+├── SKILL.md          # 主指令文件，建议保持 500 行以内
+├── reference.md      # 可选，详细参考文档
+├── template.md       # 可选，输出模板
+└── scripts/
+    └── helper.py     # 可选，辅助脚本
+```
+
+### 调用方式
+
+- **手动调用**：在对话中输入 `/skill-name [参数]`
+- **自动调用**：Claude 根据 `description` 字段判断场景后自动加载（默认行为）
+
+## 技能列表
+
+| 技能名 | 描述 |
+|--------|------|
+| — | — |
+
+## 更新技能
+
+```bash
+git pull
+```
+
+插件内容更新后，重启 Claude Code 会话即可生效。
diff --git a/skills/.gitkeep b/skills/.gitkeep
new file mode 100644
index 0000000..e69de29