clearai-dsh 0.1.0

package/presets/clearai/template/skills/scientific-critical-thinking/references/statistical_pitfalls.md

@@ -0,0 +1,506 @@
+# Common Statistical Pitfalls
+
+## P-Value Misinterpretations
+
+### Pitfall 1: P-Value = Probability Hypothesis is True
+**Misconception:** p = .05 means 5% chance the null hypothesis is true.
+
+**Reality:** P-value is the probability of observing data this extreme (or more) *if* the null hypothesis is true. It says nothing about the probability the hypothesis is true.
+
+**Correct interpretation:** "If there were truly no effect, we would observe data this extreme only 5% of the time."
+
+### Pitfall 2: Non-Significant = No Effect
+**Misconception:** p > .05 proves there's no effect.
+
+**Reality:** Absence of evidence ≠ evidence of absence. Non-significant results may indicate:
+- Insufficient statistical power
+- True effect too small to detect
+- High variability
+- Small sample size
+
+**Better approach:**
+- Report confidence intervals
+- Conduct power analysis
+- Consider equivalence testing
+
+### Pitfall 3: Significant = Important
+**Misconception:** Statistical significance means practical importance.
+
+**Reality:** With large samples, trivial effects become "significant." A statistically significant 0.1 IQ point difference is meaningless in practice.
+
+**Better approach:**
+- Report effect sizes
+- Consider practical significance
+- Use confidence intervals
+
+### Pitfall 4: P = .049 vs. P = .051
+**Misconception:** These are meaningfully different because one crosses the .05 threshold.
+
+**Reality:** These represent nearly identical evidence. The .05 threshold is arbitrary.
+
+**Better approach:**
+- Treat p-values as continuous measures of evidence
+- Report exact p-values
+- Consider context and prior evidence
+
+### Pitfall 5: One-Tailed Tests Without Justification
+**Misconception:** One-tailed tests are free extra power.
+
+**Reality:** One-tailed tests assume effects can only go one direction, which is rarely true. They're often used to artificially boost significance.
+
+**When appropriate:** Only when effects in one direction are theoretically impossible or equivalent to null.
+
+## Multiple Comparisons Problems
+
+### Pitfall 6: Multiple Testing Without Correction
+**Problem:** Testing 20 hypotheses at p < .05 gives ~65% chance of at least one false positive.
+
+**Examples:**
+- Testing many outcomes
+- Testing many subgroups
+- Conducting multiple interim analyses
+- Testing at multiple time points
+
+**Solutions:**
+- Bonferroni correction (divide α by number of tests)
+- False Discovery Rate (FDR) control
+- Prespecify primary outcome
+- Treat exploratory analyses as hypothesis-generating
+
+### Pitfall 7: Subgroup Analysis Fishing
+**Problem:** Testing many subgroups until finding significance.
+
+**Why problematic:**
+- Inflates false positive rate
+- Often reported without disclosure
+- "Interaction was significant in women" may be random
+
+**Solutions:**
+- Prespecify subgroups
+- Use interaction tests, not separate tests
+- Require replication
+- Correct for multiple comparisons
+
+### Pitfall 8: Outcome Switching
+**Problem:** Analyzing many outcomes, reporting only significant ones.
+
+**Detection signs:**
+- Secondary outcomes emphasized
+- Incomplete outcome reporting
+- Discrepancy between registration and publication
+
+**Solutions:**
+- Preregister all outcomes
+- Report all planned outcomes
+- Distinguish primary from secondary
+
+## Sample Size and Power Issues
+
+### Pitfall 9: Underpowered Studies
+**Problem:** Small samples have low probability of detecting true effects.
+
+**Consequences:**
+- High false negative rate
+- Significant results more likely to be false positives
+- Overestimated effect sizes (when significant)
+
+**Solutions:**
+- Conduct a priori power analysis
+- Aim for 80-90% power
+- Consider effect size from prior research
+
+### Pitfall 10: Post-Hoc Power Analysis
+**Problem:** Calculating power after seeing results is circular and uninformative.
+
+**Why useless:**
+- Non-significant results always have low "post-hoc power"
+- It recapitulates the p-value without new information
+
+**Better approach:**
+- Calculate confidence intervals
+- Plan replication with adequate sample
+- Conduct prospective power analysis for future studies
+
+### Pitfall 11: Small Sample Fallacy
+**Problem:** Trusting results from very small samples.
+
+**Issues:**
+- High sampling variability
+- Outliers have large influence
+- Assumptions of tests violated
+- Confidence intervals very wide
+
+**Guidelines:**
+- Be skeptical of n < 30
+- Check assumptions carefully
+- Consider non-parametric tests
+- Replicate findings
+
+## Effect Size Misunderstandings
+
+### Pitfall 12: Ignoring Effect Size
+**Problem:** Focusing only on significance, not magnitude.
+
+**Why problematic:**
+- Significance ≠ importance
+- Can't compare across studies
+- Doesn't inform practical decisions
+
+**Solutions:**
+- Always report effect sizes
+- Use standardized measures (Cohen's d, r, η²)
+- Interpret using field conventions
+- Consider minimum clinically important difference
+
+### Pitfall 13: Misinterpreting Standardized Effect Sizes
+**Problem:** Treating Cohen's d = 0.5 as "medium" without context.
+
+**Reality:**
+- Field-specific norms vary
+- Some fields have larger typical effects
+- Real-world importance depends on context
+
+**Better approach:**
+- Compare to effects in same domain
+- Consider practical implications
+- Look at raw effect sizes too
+
+### Pitfall 14: Confusing Explained Variance with Importance
+**Problem:** "Only explains 5% of variance" = unimportant.
+
+**Reality:**
+- Height explains ~5% of variation in NBA player salary but is crucial
+- Complex phenomena have many small contributors
+- Predictive accuracy ≠ causal importance
+
+**Consideration:** Context matters more than percentage alone.
+
+## Correlation and Causation
+
+### Pitfall 15: Correlation Implies Causation
+**Problem:** Inferring causation from correlation.
+
+**Alternative explanations:**
+- Reverse causation (B causes A, not A causes B)
+- Confounding (C causes both A and B)
+- Coincidence
+- Selection bias
+
+**Criteria for causation:**
+- Temporal precedence
+- Covariation
+- No plausible alternatives
+- Ideally: experimental manipulation
+
+### Pitfall 16: Ecological Fallacy
+**Problem:** Inferring individual-level relationships from group-level data.
+
+**Example:** Countries with more chocolate consumption have more Nobel laureates doesn't mean eating chocolate makes you win Nobels.
+
+**Why problematic:** Group-level correlations may not hold at individual level.
+
+### Pitfall 17: Simpson's Paradox
+**Problem:** Trend appears in groups but reverses when combined (or vice versa).
+
+**Example:** Treatment appears worse overall but better in every subgroup.
+
+**Cause:** Confounding variable distributed differently across groups.
+
+**Solution:** Consider confounders and look at appropriate level of analysis.
+
+## Regression and Modeling Pitfalls
+
+### Pitfall 18: Overfitting
+**Problem:** Model fits sample data well but doesn't generalize.
+
+**Causes:**
+- Too many predictors relative to sample size
+- Fitting noise rather than signal
+- No cross-validation
+
+**Solutions:**
+- Use cross-validation
+- Penalized regression (LASSO, ridge)
+- Independent test set
+- Simpler models
+
+### Pitfall 19: Extrapolation Beyond Data Range
+**Problem:** Predicting outside the range of observed data.
+
+**Why dangerous:**
+- Relationships may not hold outside observed range
+- Increased uncertainty not reflected in predictions
+
+**Solution:** Only interpolate; avoid extrapolation.
+
+### Pitfall 20: Ignoring Model Assumptions
+**Problem:** Using statistical tests without checking assumptions.
+
+**Common violations:**
+- Non-normality (for parametric tests)
+- Heteroscedasticity (unequal variances)
+- Non-independence
+- Linearity
+- No multicollinearity
+
+**Solutions:**
+- Check assumptions with diagnostics
+- Use robust methods
+- Transform data
+- Use appropriate non-parametric alternatives
+
+### Pitfall 21: Treating Non-Significant Covariates as Eliminating Confounding
+**Problem:** "We controlled for X and it wasn't significant, so it's not a confounder."
+
+**Reality:** Non-significant covariates can still be important confounders. Significance ≠ confounding.
+
+**Solution:** Include theoretically important covariates regardless of significance.
+
+### Pitfall 22: Collinearity Masking Effects
+**Problem:** When predictors are highly correlated, true effects may appear non-significant.
+
+**Manifestations:**
+- Large standard errors
+- Unstable coefficients
+- Sign changes when adding/removing variables
+
+**Detection:**
+- Variance Inflation Factors (VIF)
+- Correlation matrices
+
+**Solutions:**
+- Remove redundant predictors
+- Combine correlated variables
+- Use regularization methods
+
+## Specific Test Misuses
+
+### Pitfall 23: T-Test for Multiple Groups
+**Problem:** Conducting multiple t-tests instead of ANOVA.
+
+**Why wrong:** Inflates Type I error rate dramatically.
+
+**Correct approach:**
+- Use ANOVA first
+- Follow with planned comparisons or post-hoc tests with correction
+
+### Pitfall 24: Pearson Correlation for Non-Linear Relationships
+**Problem:** Using Pearson's r for curved relationships.
+
+**Why misleading:** r measures linear relationships only.
+
+**Solutions:**
+- Check scatterplots first
+- Use Spearman's ρ for monotonic relationships
+- Consider polynomial or non-linear models
+
+### Pitfall 25: Chi-Square with Small Expected Frequencies
+**Problem:** Chi-square test with expected cell counts < 5.
+
+**Why wrong:** Violates test assumptions, p-values inaccurate.
+
+**Solutions:**
+- Fisher's exact test
+- Combine categories
+- Increase sample size
+
+### Pitfall 26: Paired vs. Independent Tests
+**Problem:** Using independent samples test for paired data (or vice versa).
+
+**Why wrong:**
+- Wastes power (paired data analyzed as independent)
+- Violates independence assumption (independent data analyzed as paired)
+
+**Solution:** Match test to design.
+
+## Confidence Interval Misinterpretations
+
+### Pitfall 27: 95% CI = 95% Probability True Value Inside
+**Misconception:** "95% chance the true value is in this interval."
+
+**Reality:** The true value either is or isn't in this specific interval. If we repeated the study many times, 95% of resulting intervals would contain the true value.
+
+**Better interpretation:** "We're 95% confident this interval contains the true value."
+
+### Pitfall 28: Overlapping CIs = No Difference
+**Problem:** Assuming overlapping confidence intervals mean no significant difference.
+
+**Reality:** Overlapping CIs are less stringent than difference tests. Two CIs can overlap while the difference between groups is significant.
+
+**Guideline:** Overlap of point estimate with other CI is more relevant than overlap of intervals.
+
+### Pitfall 29: Ignoring CI Width
+**Problem:** Focusing only on whether CI includes zero, not precision.
+
+**Why important:** Wide CIs indicate high uncertainty. "Significant" effects with huge CIs are less convincing.
+
+**Consider:** Both significance and precision.
+
+## Bayesian vs. Frequentist Confusions
+
+### Pitfall 30: Mixing Bayesian and Frequentist Interpretations
+**Problem:** Making Bayesian statements from frequentist analyses.
+
+**Examples:**
+- "Probability hypothesis is true" (Bayesian) from p-value (frequentist)
+- "Evidence for null" from non-significant result (frequentist can't support null)
+
+**Solution:**
+- Be clear about framework
+- Use Bayesian methods for Bayesian questions
+- Use Bayes factors to compare hypotheses
+
+### Pitfall 31: Ignoring Prior Probability
+**Problem:** Treating all hypotheses as equally likely initially.
+
+**Reality:** Extraordinary claims need extraordinary evidence. Prior plausibility matters.
+
+**Consider:**
+- Plausibility given existing knowledge
+- Mechanism plausibility
+- Base rates
+
+## Data Transformation Issues
+
+### Pitfall 32: Dichotomizing Continuous Variables
+**Problem:** Splitting continuous variables at arbitrary cutoffs.
+
+**Consequences:**
+- Loss of information and power
+- Arbitrary distinctions
+- Discarding individual differences
+
+**Exceptions:** Clinically meaningful cutoffs with strong justification.
+
+**Better:** Keep continuous or use multiple categories.
+
+### Pitfall 33: Trying Multiple Transformations
+**Problem:** Testing many transformations until finding significance.
+
+**Why problematic:** Inflates Type I error, is a form of p-hacking.
+
+**Better approach:**
+- Prespecify transformations
+- Use theory-driven transformations
+- Correct for multiple testing if exploring
+
+## Missing Data Problems
+
+### Pitfall 34: Listwise Deletion by Default
+**Problem:** Automatically deleting all cases with any missing data.
+
+**Consequences:**
+- Reduced power
+- Potential bias if data not missing completely at random (MCAR)
+
+**Better approaches:**
+- Multiple imputation
+- Maximum likelihood methods
+- Analyze missingness patterns
+
+### Pitfall 35: Ignoring Missing Data Mechanisms
+**Problem:** Not considering why data are missing.
+
+**Types:**
+- MCAR (Missing Completely at Random): Safe to delete
+- MAR (Missing at Random): Can impute
+- MNAR (Missing Not at Random): May bias results
+
+**Solution:** Analyze patterns, use appropriate methods, consider sensitivity analyses.
+
+## Publication and Reporting Issues
+
+### Pitfall 36: Selective Reporting
+**Problem:** Only reporting significant results or favorable analyses.
+
+**Consequences:**
+- Literature appears more consistent than reality
+- Meta-analyses biased
+- Wasted research effort
+
+**Solutions:**
+- Preregistration
+- Report all analyses
+- Use reporting guidelines (CONSORT, PRISMA, etc.)
+
+### Pitfall 37: Rounding to p < .05
+**Problem:** Reporting exact p-values selectively (e.g., p = .049 but p < .05 for .051).
+
+**Why problematic:** Obscures values near threshold, enables p-hacking detection evasion.
+
+**Better:** Always report exact p-values.
+
+### Pitfall 38: No Data Sharing
+**Problem:** Not making data available for verification or reanalysis.
+
+**Consequences:**
+- Can't verify results
+- Can't include in meta-analyses
+- Hinders scientific progress
+
+**Best practice:** Share data unless privacy concerns prohibit.
+
+## Cross-Validation and Generalization
+
+### Pitfall 39: No Cross-Validation
+**Problem:** Testing model on same data used to build it.
+
+**Consequence:** Overly optimistic performance estimates.
+
+**Solutions:**
+- Split data (train/test)
+- K-fold cross-validation
+- Independent validation sample
+
+### Pitfall 40: Data Leakage
+**Problem:** Information from test set leaking into training.
+
+**Examples:**
+- Normalizing before splitting
+- Feature selection on full dataset
+- Including temporal information
+
+**Consequence:** Inflated performance metrics.
+
+**Prevention:** All preprocessing decisions made using only training data.
+
+## Meta-Analysis Pitfalls
+
+### Pitfall 41: Apples and Oranges
+**Problem:** Combining studies with different designs, populations, or measures.
+
+**Balance:** Need homogeneity but also comprehensiveness.
+
+**Solutions:**
+- Clear inclusion criteria
+- Subgroup analyses
+- Meta-regression for moderators
+
+### Pitfall 42: Ignoring Publication Bias
+**Problem:** Published studies overrepresent significant results.
+
+**Consequences:** Overestimated effects in meta-analyses.
+
+**Detection:**
+- Funnel plots
+- Trim-and-fill
+- PET-PEESE
+- P-curve analysis
+
+**Solutions:**
+- Include unpublished studies
+- Register reviews
+- Use bias-correction methods
+
+## General Best Practices
+
+1. **Preregister studies** - Distinguish confirmatory from exploratory
+2. **Report transparently** - All analyses, not just significant ones
+3. **Check assumptions** - Don't blindly apply tests
+4. **Use appropriate tests** - Match test to data and design
+5. **Report effect sizes** - Not just p-values
+6. **Consider practical significance** - Not just statistical
+7. **Replicate findings** - One study is rarely definitive
+8. **Share data and code** - Enable verification
+9. **Use confidence intervals** - Show uncertainty
+10. **Think causally carefully** - Most research is correlational

package/presets/clearai/template/skills/skill-creator/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: skill-creator
+description: |
+  【元技能·创作工艺·触发词: 创建技能, 新建skill, 写skill, 改进技能, 优化skill, 沉淀SOP, 把流程做成技能, 让我以后能复用, 技能描述触发不准】把可复用经验结晶成一个好用的 Skill 的工艺指南。无论你是要从零创建新 Skill、改进已有 Skill、还是优化它的触发描述——动手写 clear/skills 下任何 SKILL.md 之前，都先加载本技能取工艺，确保描述是好触发器、结构精简、解释了 why。
+  不适用：写普通文档、README 或代码注释（那是内容工作，不是技能沉淀）；
+  一次性经验先落 memory，够通用了再回来沉淀成技能。
+license: MIT
+metadata:
+  tier: system
+  origin: template
+  version: "1.0-clearai"
+---
+
+# Skill Creator（ClearAI 版）
+
+把"这次怎么做成的"结晶为一个**未来千百次可复用**的 Skill。本技能是动态 Skill 进化 loop 的工艺底座：agent 沉淀/改进 Skill 前先读它，保证产出质量。
+
+## 何时用 · 三种入口
+
+1. **创建新 Skill**：手上有一段值得复用的流程（常来自 WriteMemory 的 Trigger-Action-Validation 三元组）。
+2. **改进已有 Skill**：某 Skill 用下来有缺漏，要补 checklist / 修步骤 / 改描述。
+3. **优化触发描述**：Skill 该触发时没触发（欠触发），调 description。
+
+判断走哪条：先扫外脑索引 `<skills>`/`<candidate_skills>`，有匹配就改、没有就建、都不够通用就只留 memory lesson。
+
+## 在 ClearAI 里怎么落地（工具映射）
+
+写 skill 的**唯一**方式是 `SaveSkill`（勿用 write/edit 改 skill——会被拦）：
+- **新建** → `SaveSkill(skill="<name>", content=<SKILL.md 全文>)`。系统自动盖 `tier=candidate`、校验 frontmatter，落入「技能收件箱」等采纳。
+- **改进已有** → `SaveSkill(skill="<已有名>", content=<改进后全文>)`。若该 skill 是 trusted/system，系统自动生成「候选改版」、**活版不动**，采纳时才替换。
+- **子资源** → `SaveSkill(skill="<name>", path="scripts/x.py"|"references/y.md", content=...)`，一次写一个文件（全文）。
+- SaveSkill 不弹写时审批：所有产物都进收件箱，**用户采纳是唯一的生效闸**。
+- **不要**在正文引用子代理、`claude -p`、浏览器评测器等 ClearAI 没有的能力。
+
+## frontmatter 契约
+
+```yaml
+name: <kebab-case>          # 仅小写字母/数字/连字符
+description: |
+  【阶段·触发词: kw1, kw2, kw3】一句话能力。适用：...；不适用：指向其他 skill。
+metadata:
+  tier: candidate           # 系统会自动盖，无需手填
+```
+
+**description 是触发的唯一机制，也是最该用心的地方**：
+- 首行用 `【阶段·触发词: ...】` 列 3-6 个用户任务里会出现、能命中本 skill 的关键词。
+- 要**"pushy"对抗欠触发**：明确写"当用户提到 X、Y、Z 时就用本技能，即使没明说要用"。当前模型倾向于该用 skill 时不用，描述写得主动一点能纠偏。
+- 写清**适用 / 不适用**，不适用处指向更合适的 skill 名，减少误触发。
+
+## 结构与渐进式披露
+
+Skill 三级加载，写时按此分层、保持每层精简：
+1. **name + description**（始终在 context）——触发判断只看这层。
+2. **SKILL.md 正文**（触发后加载，目标 <500 行）——SOP 主干。
+3. **子资源**（按需读/执行）——`scripts/` 确定性代码、`references/` 详细文档、`assets/` 产物模板。
+
+正文超长就加一层层级：SKILL.md 留主干 + 指针，细节挪进 `references/`，并在指针处说明"何时去读"。多领域/多框架按变体拆 `references/<variant>.md`，正文只做选择与编排。
+
+## 先分清这是谁的活
+
+harness 执行不变量（与具体任务无关、没商量余地），skill 提供工艺（这类事怎么做得好），
+agent 做接合（把工艺用到具体情境）。动笔前先问这条内容属于哪一层——放错层的内容不会报错，
+只会慢慢腐坏。
+
+**平台已经强制的，写「为什么」而不是重抄规则。** 读者撞上拒绝时需要理由才能改对；一份和
+平台重复的规则表既帮不上忙，还会先于平台过期。
+
+**平台强制不了的，才是 skill 的本职。** 本仓的例子：`verify` 阶段隔离的是数据目录与 HOME，
+不隔离网络，所以「运行时不引 CDN」在验证时看不出来，产物拿到没网的地方才炸——这条只能靠
+工艺纪律加技能自带的检查脚本兜住。这类内容写得越具体越好。
+
+**数据的形状归上游技能的契约或 harness 的校验**，别焊进呈现/渲染类技能。调用时自然会带
+进来；写死了反而让技能在别的数据上用不了。
+
+### 别复述平台行为，那会漂移
+
+写「平台会怎样」的句子迟早和平台对不上，而读者拿它当真。本仓踩过：某技能写「手建目录不会
+被识别，且这个失败是静默的」，而平台早已给出带修复建议的显式错误。这句不只是过时——它暗示
+agent 不必去读错误信息，可答案恰恰就在那里。
+
+写「你该怎么做、以及为什么」，把「平台实际怎么反应」留给它自己的错误信息去说，那永远是最新的。
+
+### 平台常量分两种
+
+判据只有一个：**这个数字会改变 agent 的下一步动作吗？**
+
+会就写。一个外部调用的超时秒数是「这个操作要不要拆成后台作业」的直接输入，不写他就没法判断。
+
+不会就别抄。state 的字节上限对 agent 没有决策价值，写「有上限、大数组换成摘要与 state_ref」
+就够了，具体数字让平台的拒绝去说。抄下来的常量没有任何机制会随平台更新，而它看起来永远
+像是准确的。
+
+## 写作风格（决定 skill 好不好用）
+
+- **解释 why，而非堆大写 MUST**。模型很聪明、有 theory of mind，给它理由比给铁律更有效、更通用。写到 ALWAYS/NEVER 全大写或极刚性结构时，是黄旗——回头重述成"为什么这样做"。
+- 用**祈使句**，面向通用场景而非过拟合到具体例子。
+- 先写草稿，再以新眼光重看一遍精简——删掉不拉动效果的部分。
+
+## 评测 = 复用 ClearAI 已有回路（不要另造）
+
+skill-creator 原版有一套子代理 benchmark + HTML viewer。在 ClearAI 里**用我们已有的两条回路顶替**：
+
+- **人评** = 把 candidate 交给用户在**技能收件箱**采纳/驳回。采纳即"通过评审"。
+- **量化** = 看该 skill 的 **uses/wins 遥测**（`clear/audit/skill_usage.jsonl` 聚合，索引按 wins/uses 排序）。被反复加载且关联成功计划多，说明它好用，自然上浮。
+- **重复脚本信号** = 若多次任务里你都手写了同一个脚本，把它写一次放进该 skill 的 `scripts/` 并在正文引用，省掉未来每次重造轮子。
+
+## 更细的写作模式 / 示例 / 反例
+
+需要 description 优化细则、好/坏示例、近义反例设计、领域拆分模板时，读 `references/authoring-guide.md`（按需加载，不必一上来就读）。

package/presets/clearai/template/skills/skill-creator/references/authoring-guide.md

@@ -0,0 +1,89 @@
+# 创作工艺细则（按需加载）
+
+SKILL.md 已讲核心。本文是第二层：description 优化、好坏示例、反例设计、领域拆分。需要时再读对应小节。
+
+## 目录
+- 1. description 写法与"pushy"度
+- 2. 触发词怎么选
+- 3. 好例 / 坏例
+- 4. 适用 / 不适用 的写法
+- 5. 输出格式与示例模式
+- 6. 何时该 bundle 脚本
+- 7. 多领域拆分
+- 8. 自检清单
+
+## 1. description 写法与"pushy"度
+
+description 是 Skill 触发的唯一依据。模型只看 name+description 决定要不要加载本 skill。两个常见失败：
+- **欠触发**（更常见）：该用时不用。对策是把描述写得主动——显式列触发场景，并加一句"即使用户没明说要用本技能，只要涉及 X/Y/Z 就用"。
+- **过触发**：不该用时也用。对策是写清"不适用"并指向更合适的 skill。
+
+把握度：宁可稍微 pushy 一点纠正欠触发，但用"不适用"兜住边界。
+
+## 2. 触发词怎么选
+
+放进 `【阶段·触发词: ...】` 的词，应是**用户真实任务文本里会出现**的词，而非你对该领域的术语。想象用户会怎么口语化地描述这个需求：
+- 包含同义/近义说法（正式的、口语的）。
+- 包含用户**不点名**本 skill、但显然需要它的场景词。
+- 3-6 个即可，过多稀释。
+
+## 3. 好例 / 坏例
+
+**description 坏例**（太被动、无触发场景）：
+> 引用管理：检索论文元数据，DOI 转 BibTeX。
+
+**好例**（主动 + 触发场景 + 边界）：
+> 【引用管理·触发词: 引用, 参考文献, BibTeX, DOI, 文末引用, 去重】检索论文元数据、DOI→BibTeX、校验去重。适用：预研/综述报告文末引用统一、交付前引用准确性检查。不适用：全文综述撰写（用 literature-review）。
+
+## 4. 适用 / 不适用 的写法
+
+- **适用**：列 2-4 个该 skill 最该上场的具体情境。
+- **不适用**：列易混淆的邻近情境，并**指向应该用的 skill 名**。这既减少误触发，也帮模型在多 skill 竞争时选对。
+
+## 5. 输出格式与示例模式
+
+要求固定产出格式时，直接在正文给模板：
+```markdown
+## 报告结构（严格按此）
+# 标题
+## 摘要
+## 关键发现
+## 建议
+```
+
+给示例帮助很大，用 输入→输出 对照：
+```markdown
+**示例 1**
+输入：为用户认证加了 JWT
+输出：feat(auth): 实现基于 JWT 的认证
+```
+
+## 6. 何时该 bundle 脚本
+
+读你自己几次任务的过程记录：如果**多次**都独立写了类似的 `create_docx.py` / `build_chart.py` / 同样的多步处理，这是强信号——把它写一次放进该 skill 的 `scripts/`，正文里指明"用 scripts/xxx.py 而非每次重写"。每个未来调用都省掉重造轮子。
+
+ClearAI 里脚本由 bash 工具执行，写类动作由系统策略治理。脚本要自带用法注释、参数清晰、可独立运行。
+
+## 7. 多领域拆分
+
+一个 skill 覆盖多领域/框架时，按变体拆 `references/`，正文只做选择与编排：
+```
+cloud-deploy/
+├── SKILL.md         # 工作流 + 如何选变体
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
+模型只读相关那一个变体文件，省 context。大参考文件（>300 行）开头放目录。
+
+## 8. 自检清单（写完回看）
+
+- [ ] description 首行有 `【阶段·触发词: ...】`，词是用户会说的话。
+- [ ] 写了"适用 / 不适用"，不适用指向了别的 skill。
+- [ ] 主动度够（不会欠触发），但有边界（不会过触发）。
+- [ ] 正文是祈使句、解释了 why、没堆大写 MUST。
+- [ ] SKILL.md 主干精简（<500 行），长内容挪进 references/ 并留指针。
+- [ ] 重复出现的脚本已 bundle 进 scripts/。
+- [ ] name 是 kebab-case；frontmatter 只含允许的 key。
+- [ ] 评测交给收件箱（人评）+ uses/wins（量化），没有另造评测机器。