add README guidance to skill workflow

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():