适用于大模型的 Skill 创作标准#

1
my-skill/
2
├── SKILL.md                    # 必需：触发 + 工作流
3
├── agents/
4
│   └── openai.yaml             # 推荐：UI 展示元数据
5
├── scripts/                    # 可选：确定性逻辑
6
│   └── run_task.py
7
├── references/                 # 可选：按需加载知识
8
│   ├── schema.md
9
│   └── policies.md
10
└── assets/                     # 可选：模板或输出素材
11
    └── report-template.md

1
description: 帮助处理文档。

1
description: 面向技术文档的创建、改写与结构化提取。当用户请求涉及 Markdown/Docx 文档的章节重组、术语统一、格式修复、摘要生成时使用；支持输入为 .md、.docx 与纯文本片段。

1
skill-quality-gate/
2
├── SKILL.md
3
├── scripts/
4
│   └── check_frontmatter.py
5
└── references/
6
    └── style-guide.md

1
---
2
name: skill-quality-gate
3
description: 校验并修复 Markdown 文章的元数据与结构一致性。当用户请求“检查文章规范”“修复 frontmatter”“统一发布格式”或需要批量审查博客文章时使用；输入通常为 .md 文件。
4
---
5

6
# Skill Quality Gate
7

8
## Quick Start
9

10
1. 读取目标 Markdown 文件的 frontmatter。
11
2. 用 `scripts/check_frontmatter.py` 执行规范检查。
12
3. 根据检查结果修复字段缺失、类型不匹配和日期格式问题。
13

14
## Workflow
15

16
1. 收集输入文件路径并逐个检查。
17
2. 若 `title/published/description/tags/category/draft` 缺失，则补全。
18
3. 若 `published` 不是 `YYYY-MM-DD`，转换为标准格式。
19
4. 输出修复摘要，包含：`fixed_files`、`warnings`、`manual_review_items`。
20

21
## Failure Handling
22

23
1. 解析 frontmatter 失败时，返回文件名和失败行号。
24
2. 禁止跳过错误继续写入，必须先报告再等待用户确认。
25

26
## References
27

28
- 当需要字段命名规范时，读取 `references/style-guide.md`。

1
#!/usr/bin/env python3
2
import re
3
import sys
4
from pathlib import Path
5

6
REQUIRED_KEYS = {"title", "published", "description", "tags", "category", "draft"}
7
DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
8

9

10
def read_frontmatter(text: str) -> str:
11
    if not text.startswith("---\n"):
12
        raise ValueError("missing frontmatter start")
13
    end = text.find("\n---\n", 4)
14
    if end == -1:
15
        raise ValueError("missing frontmatter end")
16
    return text[4:end]
17

18

19
def parse_keys(frontmatter: str) -> dict:
20
    result = {}
21
    for line in frontmatter.splitlines():
22
        if ":" not in line:
23
            continue
24
        key, value = line.split(":", 1)
25
        result[key.strip()] = value.strip()
26
    return result
27

28

29
def validate(path: Path) -> list[str]:
30
    errors = []
31
    content = path.read_text(encoding="utf-8")
32
    fm = read_frontmatter(content)
33
    data = parse_keys(fm)
34

35
    missing = sorted(REQUIRED_KEYS - data.keys())
36
    if missing:
37
        errors.append(f"missing keys: {', '.join(missing)}")
38

39
    if "published" in data and not DATE_RE.match(data["published"].strip("'\"")):
40
        errors.append("published must be YYYY-MM-DD")
41

42
    if "draft" in data and data["draft"] not in {"true", "false"}:
43
        errors.append("draft must be true/false")
44

45
    return errors
46

47

48
def main() -> int:
49
    if len(sys.argv) < 2:
50
        print("usage: check_frontmatter.py <file1> [file2 ...]")
51
        return 1
52

53
    has_error = False
54
    for item in sys.argv[1:]:
55
        path = Path(item)
56
        try:
57
            errs = validate(path)
58
        except Exception as exc:
59
            print(f"{path}: parse error: {exc}")
60
            has_error = True
61
            continue
62

63
        if errs:
64
            has_error = True
65
            print(f"{path}:")
66
            for err in errs:
67
                print(f"  - {err}")
68
        else:
69
            print(f"{path}: ok")
70

71
    return 1 if has_error else 0
72

73

74
if __name__ == "__main__":
75
    raise SystemExit(main())

1
# Style Guide
2

3
## Required Frontmatter Keys
4

5
- title: string
6
- published: YYYY-MM-DD
7
- description: string
8
- tags: array
9
- category: string
10
- draft: boolean
11

12
## Writing Rules
13

14
1. 标题控制在 8 到 28 个字。
15
2. 首段必须说明文章目标与适用对象。
16
3. 命令示例统一使用代码块并标注语言。