Skill 设计原则

# ❌ 模糊
Trigger: 用户在创造性工作时启用

# ✅ 显式
Trigger:
  - starts_with_any: ["我要加", "我需要实现", "开一个新", "新增功能"]
  - or_intent: [create_feature, modify_behavior, add_capability]
  - not_when: [reading, explaining, debugging]

# ❌ 文档口吻
本节描述最佳实践：思考时要 brainstorm，写代码要 TDD...

# ✅ 契约口吻
You MUST brainstorm before code.
You MUST run `pytest tests/` before claiming done.
DO NOT ship with `as any` in diff.

my-review-skill/
├── SKILL.md              ← 主 prompt-契约
├── references/
│   ├── patterns.md       ← "好的 review 该这样写"
│   ├── antipatterns.md   ← "避免这种 review 形态"
│   └── severity.md       ← "🟥/🟧/🟨 的判定标准"
└── skills/
    └── auto-review.py    ← 可选的派生 sub-skill

When reviewing, follow the rules in `references/patterns.md`.
For severity classification, see `references/severity.md`.

When you have produced:
  - 一个 spec.md 包含目标、输入、输出、约束（4 节齐全）
  - 用户对 spec 答 yes / go
then brainstorming is DONE. Proceed to implementation.

# Failure modes
- If user says "skip brainstorm, just code":
  - Stop and write code; mark this session as `--no-brainstorm`.
  - DO NOT silently skip and continue the brainstorm anyway.

- If user provides conflicting constraints:
  - Ask one short yes/no question to disambiguate.
  - DO NOT pick one and proceed.

# Output prefix
每次你在 brainstorm 时，回复开头写:
  `[brainstorming] ...`
让用户在 transcript 里能 grep `[brainstorming]` 判断是否触发.

在 brainstorm 结束时, 用一行回包:
  `[brainstorming complete] spec.md at <path>, user agree: yes/no`

如果你跳过了, 回报:
  `[brainstorming skipped] reason: <短理由>`

反模式             | 现象                                  | 修正
─────────────────────────────────────────────────────────
过宽 trigger     | "凡是涉及代码" → 触发 99%               | 收窄到具体场景
过深细节          | 主 SKILL.md 5000 行                    | 拆 references/
无 DONE 条件     | Skill 流程跑过、没出口                 | 加 OK 判据
无失败模式     | 用户跳过时模型仍执行 → strong 武断       | 加显式 skip 路径
无自报           | 事后无法判断是否真到位                  | 要求开头 / 结尾标记
模糊命令     | "考虑" "可以" "建议"                   | "you MUST" / "DO NOT"
过深嵌套       | Skill 内嵌 Skill 内嵌 Skill → 维护噩梦   | 至多 2 层；交付用 dispatch

# brainstorming/SKILL.md

<description>
MUST use before any creative work - creating features, building components,
adding functionality, or modifying behavior. Explores user intent,
requirements and design before implementation.
</description>

<trigger>
starts_with_any: ["我要加", "新增", "重构", "实现 a feature", "新增功能"]
or_intent:       [create_feature, modify_behavior]
NOT_when:        [explaining, debugging, reading]
</trigger>

<flow>
1. Interview the user (max 5 questions):
   - Target users
   - Inputs / outputs
   - Constraints
   - Acceptance criteria
   - Known failure modes
2. Write `spec.md` capturing the answers
3. Wait for user to say "go" before implementing
</flow>

<done>
spec.md exists and user explicitly says "go" / "implement"
</done>

<failure>
- User says "skip": write code, log `[brainstorming skipped: user-skip]`
- User provides conflict: ask 1 yes/no question to disambiguate
</failure>

<references>
- patterns.md
- antipatterns.md
</references>

# pre-commit-safety/SKILL.md
Use before claiming work is complete.

<trigger>
intent: commit_and_pr
keywords: ["commit", "提 PR", "推上"]
</trigger>

<flow>
1. Run `detect-secrets scan`
2. Run `bandit -r src/` or `semgrep scan`
3. Run `pytest -x`
4. Any failure → stop, report, do not proceed
</flow>

# multi-explore/SKILL.md
MUST use when facing 2+ independent discovery tasks.

<trigger>
intent: parallel_search
</trigger>

<flow>
For each task, dispatch `explore` subagent:
  task(subagent_type="explore", prompt="...")
Await `asyncio.gather`. Merge results to single report.
</flow>