diff --git a/openspec/config.yaml b/openspec/config.yaml
index 347e31a..d8ab226 100644
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -6,4 +6,16 @@ context: |
     所有开发的 skill 都放在「skills」目录下，每个子目录都代表一个 skill，目录名为 skill 的名称；
     skill 名称统一加上「lyxy-」前缀；
     开发过程中的文档使用中文，面向中文开发者进行交流；
-    「document」下是 skill 开发的相关规范文档；
+
+    Skill 编写规范：
+    渐进式披露三层结构：
+    第一层（YAML前置元数据）始终加载用于触发判断；第二层（SKILL.md正文）相关时加载含核心指令；第三层（references/）按需加载存放详细文档。
+    YAML前置元数据：
+    name用kebab-case与文件夹名一致；description少于1024字符必须包含「做什么」和「何时使用」；禁止XML标签；可选compatibility和metadata字段。
+    description编写：[功能描述]+[触发条件/用户短语]+[关键能力]。具体场景包含触发短语和文件类型，通用工具保持宽泛。
+    SKILL.md正文章节：Purpose简要用途、When to Use适用场景、Quick Reference核心命令、Workflow执行步骤、References链接。长度建议少于5000字，详细内容移至references/。
+    references/目录：examples.md详细示例、error-handling.md错误处理、best-practices.md最佳实践。
+    常见模式：顺序工作流编排带验证关卡、迭代优化循环、上下文感知选择工具、领域智能嵌入专业知识。
+    故障排除：不触发检查description触发短语；过度触发添加负面触发器更具体化；指令不遵循保持简洁关键指令放顶部用项目符号。
+
+    更多skill开发技巧和规范参考「document」下的文档；