add README guidance to skill workflow

skiff/README.md

@@ -176,8 +176,8 @@ skiff 不保存 token。可以使用 `company/code-review`，也可以使用
 
 | 命令 | 说明 |
 |------|------|
-| `skiff create <name> [--idea TEXT] [--from-project PATH]` | 从模板创建草稿到 `~/.skills/.drafts/` |
-| `skiff check <name>` | 校验草稿或正式 skill |
+| `skiff create <name> [--idea TEXT] [--from-project PATH]` | 从模板创建含 `SKILL.md`、`README.md` 的草稿 |
+| `skiff check <name>` | 校验草稿或正式 skill，包括人类使用说明 |
 | `skiff finalize <name>` | 校验草稿并移动到正式 `skills/` |
 | `skiff doctor [--target all] [--fix]` | 检查软链健康状态，`--fix` 自动修复 |
 
@@ -187,7 +187,7 @@ skiff 不保存 token。可以使用 `company/code-review`，也可以使用
 
 ```bash
 skiff create my-skill --idea "描述要解决的重复问题" --from-project .
-# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
+# 由 Agent 完善草稿中的 SKILL.md 和 README.md
 skiff check my-skill
 skiff finalize my-skill
 skiff publish skills/my-skill -m "add my-skill" --push

skiff/cli.py

@@ -1001,6 +1001,16 @@ def cmd_create(args: argparse.Namespace) -> None:
         flags=re.MULTILINE,
     )
     skill_md.write_text(content, encoding="utf-8")
+    readme = dst / "README.md"
+    if readme.is_file():
+        readme_content = re.sub(
+            r"^#\s+skill-name\s*$",
+            f"# {args.name}",
+            readme.read_text(encoding="utf-8"),
+            count=1,
+            flags=re.MULTILINE,
+        )
+        readme.write_text(readme_content, encoding="utf-8")
     brief = {
         "name": args.name,
         "idea": args.idea or "",

skiff/skills.py

@@ -196,8 +196,24 @@ def validate_skill_dir(skill_dir: Path, expected_name: str) -> list[str]:
     """返回 skill 目录中的校验问题；空列表表示通过。"""
     issues: list[str] = []
     skill_md = skill_dir / "SKILL.md"
+    readme = skill_dir / "README.md"
     if not skill_md.is_file():
         return ["缺少 SKILL.md"]
+    if not readme.is_file():
+        issues.append("缺少 README.md（面向人类的使用说明）")
+    else:
+        readme_text = readme.read_text(encoding="utf-8")
+        if not readme_text.strip():
+            issues.append("README.md 为空")
+        if re.search(r"^#\s+skill-name\s*$", readme_text, re.MULTILINE):
+            issues.append("README.md 存在模板占位内容: skill-name")
+        for placeholder in (
+            "用一句话告诉使用者这个 skill 能解决什么问题",
+            "给出用户可以直接说出的典型请求",
+            "给出一条可以直接交给 Agent 的示例请求",
+        ):
+            if placeholder in readme_text:
+                issues.append(f"README.md 存在模板占位内容: {placeholder}")
 
     text = skill_md.read_text(encoding="utf-8")
     if not text.strip():