Back to Details

devtu-optimize-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Optimizing ToolUniverse Skills

优化ToolUniverse技能

Best practices for creating high-quality ToolUniverse research skills that produce detailed, evidence-graded reports with proper source attribution.
打造高质量ToolUniverse研究技能的最佳实践，此类技能可生成带有明确来源归因、经过证据分级的详尽报告。

When to Use This Skill

适用场景

Apply when:
  • Creating new ToolUniverse research skills
  • Reviewing/improving existing skills
  • User complains about missing details, noisy results, or unclear reports
  • Skill produces process-heavy instead of content-heavy output
  • Tools are failing silently or returning empty results
适用于以下情况：
  • 创建新的ToolUniverse研究技能
  • 审核/改进现有技能
  • 用户反馈报告存在细节缺失、结果冗余或表述模糊问题
  • 技能输出以流程描述为主，而非核心内容
  • 工具静默失败或返回空结果

Core Optimization Principles

核心优化原则

1. Tool Interface Verification (Pre-flight Check)

1. 工具接口验证（预检查）

Problem: Tool APIs change parameter names over time, or skills are written with incorrect parameter assumptions. This causes silent failures - tools return empty results without errors.
Solution: Verify tool parameters before calling unfamiliar tools:
python
undefined
问题：工具API的参数名称会随时间变更，或技能编写时对参数存在错误假设，导致工具静默失败——返回空结果但无错误提示。
解决方案：调用不熟悉的工具前，先验证工具参数：
python
undefined

Always check tool params to prevent silent failures

Always check tool params to prevent silent failures

tool_info = tu.tools.get_tool_info(tool_name="Reactome_map_uniprot_to_pathways")
tool_info = tu.tools.get_tool_info(tool_name="Reactome_map_uniprot_to_pathways")

Reveals: takes 
id
not 
uniprot_id

Reveals: takes 
id
not 
uniprot_id


**Maintain a known corrections table** in skills that use many tools:

| Tool | WRONG Parameter | CORRECT Parameter |
|------|-----------------|-------------------|
| `Reactome_map_uniprot_to_pathways` | `uniprot_id` | `id` |
| `ensembl_get_xrefs` | `gene_id` | `id` |
| `GTEx_get_median_gene_expression` | `gencode_id` only | `gencode_id` + `operation="median"` |
| `OpenTargets_*` | `ensemblID` | `ensemblId` (camelCase) |

**Rule**: Before calling any tool for the first time in a skill, confirm params via `get_tool_info()` once per tool family, or maintain a vetted param map in the skill.

**Why this matters**: Retry logic won't help if you're calling a tool with wrong parameter names - it will consistently return empty. This is different from API flakiness.

在使用多工具的技能中**维护已知修正表**：

| 工具 | 错误参数 | 正确参数 |
|------|-----------------|-------------------|
| `Reactome_map_uniprot_to_pathways` | `uniprot_id` | `id` |
| `ensembl_get_xrefs` | `gene_id` | `id` |
| `GTEx_get_median_gene_expression` | `gencode_id` only | `gencode_id` + `operation="median"` |
| `OpenTargets_*` | `ensemblID` | `ensemblId` (小驼峰) |

**规则**：在技能中首次调用任意工具前，需通过`get_tool_info()`确认参数（每个工具家族只需确认一次），或在技能中维护经过验证的参数映射表。

**重要性**：若使用错误的参数名称调用工具，重试逻辑无法解决问题——工具会持续返回空结果，这与API不稳定的情况不同。

2. Foundation Data Layer (Path 0)

2. 基础数据层（第0阶段）

Problem: Skills query specialized tools for each section independently, missing data that a comprehensive aggregator already has. Results are inconsistent when specialized tools fail.
Solution: Identify if your domain has a comprehensive aggregator and query it FIRST before specialized tools.
Examples by domain:
DomainFoundation SourceWhat It Provides
Drug targetsOpen TargetsDiseases, tractability, safety, drugs, GO, publications, mouse models
ChemicalsPubChemProperties, bioactivity, patents, literature
DiseasesOpen Targets / OMIMGenes, drugs, phenotypes, literature
GenesMyGene / EnsemblAnnotations, cross-refs, GO, pathways
Pattern:
markdown
undefined
问题：技能独立查询各领域的专用工具，忽略了综合聚合器已有的数据。当专用工具失效时，结果会出现不一致的情况。
解决方案：确认你的研究领域是否存在综合聚合器，并在调用专用工具前优先查询它。
各领域示例：
领域基础数据源提供内容
药物靶点Open Targets疾病、可成药性、安全性、药物、GO注释、出版物、小鼠模型
化学物质PubChem属性、生物活性、专利、文献
疾病Open Targets / OMIM基因、药物、表型、文献
基因MyGene / Ensembl注释、交叉引用、GO注释、通路
模式：
markdown
undefined

Workflow

工作流

Phase 0: Foundation Data (aggregator query) Phase 1: Disambiguation (ID resolution, collision detection) Phase 2: Specialized Queries (fill gaps from Phase 0) Phase 3: Report Synthesis

**Why this works**: The aggregator provides reliable baseline data across multiple sections. Specialized tools then add depth or fill gaps, rather than being the sole source.
阶段0：基础数据（聚合器查询） 阶段1：消歧（ID解析、冲突检测） 阶段2：专用查询（填补阶段0的空白） 阶段3：报告合成

**优势**：聚合器可提供多领域的可靠基准数据，专用工具则用于补充深度信息或填补空白，而非作为唯一数据源。

3. Versioned Identifier Handling

3. 版本化标识符处理

Problem: Some APIs require versioned identifiers (e.g., GTEx needs 
ENSG00000123456.12
), while others reject them. Skills fail silently when using the wrong format.
Solution: During ID resolution, capture BOTH versioned and unversioned forms:
python
ids = {
    'ensembl': 'ENSG00000123456',           # Unversioned (most APIs)
    'ensembl_versioned': 'ENSG00000123456.12'  # Versioned (GTEx, some others)
}
问题：部分API需要版本化标识符（如GTEx需要
ENSG00000123456.12
），而另一些API会拒绝这类标识符。使用错误格式时，技能会静默失败。
解决方案：在ID解析过程中，同时捕获版本化和非版本化两种形式：
python
ids = {
    'ensembl': 'ENSG00000123456',           # 非版本化（多数API适用）
    'ensembl_versioned': 'ENSG00000123456.12'  # 版本化（适用于GTEx及其他部分API）
}

Get version from Ensembl lookup

从Ensembl查询获取版本信息

gene_info = tu.tools.ensembl_lookup_gene(id=ensembl_id, species="human") if gene_info and gene_info.get('version'): ids['ensembl_versioned'] = f"{ensembl_id}.{gene_info['version']}"

**Fallback strategy**:
1. Try unversioned first (more portable)
2. If empty, try versioned
3. Document which format worked

**Common versioned ID APIs**: GTEx, GENCODE, some Ensembl endpoints
gene_info = tu.tools.ensembl_lookup_gene(id=ensembl_id, species="human") if gene_info and gene_info.get('version'): ids['ensembl_versioned'] = f"{ensembl_id}.{gene_info['version']}"

** fallback策略**：
1. 优先尝试非版本化格式（兼容性更强）
2. 若返回空结果，尝试版本化格式
3. 记录哪种格式有效

**常见需要版本化ID的API**：GTEx、GENCODE、部分Ensembl端点

4. Disambiguation Before Research

4. 研究前先消歧

Problem: Skills that jump straight to literature search often miss target details or retrieve irrelevant papers due to naming collisions.
Solution: Add a disambiguation phase before any literature search:
markdown
undefined
问题：直接跳转至文献搜索的技能常因命名冲突，错过目标细节或检索到无关论文。
解决方案：在任何文献搜索前添加消歧阶段：
markdown
undefined

Phase 1: Target Disambiguation (Default ON)

阶段1：目标消歧（默认开启）

1.1 Resolve Official Identifiers

1.1 解析官方标识符

  • UniProt accession (canonical protein)
  • Ensembl gene ID + version (for expression data)
  • NCBI Gene ID (for literature)
  • ChEMBL target ID (for drug data)
  • UniProt登录号（标准蛋白）
  • Ensembl基因ID + 版本（用于表达数据）
  • NCBI基因ID（用于文献）
  • ChEMBL靶点ID（用于药物数据）

1.2 Gather Synonyms and Aliases

1.2 收集同义词与别名

  • All known gene symbols
  • Protein name variants
  • Historical names
  • 所有已知基因符号
  • 蛋白名称变体
  • 历史名称

1.3 Detect Naming Collisions

1.3 检测命名冲突

  • Search "[SYMBOL]"[Title] - review top 20 results
  • If >20% off-topic → identify collision terms
  • Build negative filter: NOT [collision1] NOT [collision2]
  • 搜索"[符号]"[标题] - 查看前20条结果
  • 若超过20%结果偏离主题 → 识别冲突术语
  • 构建负面过滤条件：NOT [冲突术语1] NOT [冲突术语2]

1.4 Get Baseline Profile (from annotation DBs, not literature)

1.4 获取基准概况（来自注释数据库，而非文献）

  • Protein domains (InterPro)
  • Subcellular location (HPA)
  • Tissue expression (GTEx)
  • GO terms and pathways

**Why this works**: Annotation databases provide reliable baseline data even when literature is sparse or noisy.
  • 蛋白结构域（InterPro）
  • 亚细胞定位（HPA）
  • 组织表达（GTEx）
  • GO术语与通路

**优势**：即使文献数据稀疏或冗余，注释数据库也能提供可靠的基准数据。

5. Report-Only Output (Hide Search Process)

5. 仅报告输出（隐藏搜索流程）

Problem: Users don't want to see "searched 8 databases, found 1,247 papers, deduplicated to 892..."
Solution: Output structure:
FileContentWhen
[topic]_report.md
Narrative findings onlyAlways (default)
[topic]_bibliography.json
Full deduplicated papersAlways
methods_appendix.md
Search methodologyOnly if requested
In the report:
  • ✅ DO: "The literature reveals three main therapeutic approaches..."
  • ❌ DON'T: "I searched PubMed, OpenAlex, and EuropePMC, finding 342 papers..."
问题：用户不想看到“检索了8个数据库，找到1247篇论文，去重后剩余892篇...”这类内容。
解决方案：输出结构如下：
文件内容输出时机
[topic]_report.md
仅包含叙事性研究发现始终输出（默认）
[topic]_bibliography.json
完整的去重论文数据始终输出
methods_appendix.md
搜索方法论仅在用户请求时输出
报告撰写要求：
  • ✅ 正确写法：“文献显示存在三种主要治疗方法...”
  • ❌ 错误写法：“我检索了PubMed、OpenAlex和EuropePMC，找到342篇论文...”

6. Evidence Grading

6. 证据分级

Problem: A review article mention is treated the same as a mechanistic study with direct evidence.
Solution: Apply evidence tiers to every claim:
TierSymbolCriteria
T1★★★Mechanistic study with direct evidence
T2★★☆Functional study (knockdown, overexpression)
T3★☆☆Association (screen hit, GWAS, correlation)
T4☆☆☆Mention (review, text-mined, peripheral)
In report:
markdown
ATP6V1A drives lysosomal acidification [★★★: PMID:12345678] and has been 
implicated in cancer progression [★☆☆: PMID:23456789, TCGA expression data].
Required locations for evidence grades:
  1. Executive Summary - key disease claims
  2. Disease Associations - every disease link
  3. Key Papers table - evidence tier column
  4. Recommendations - reference evidence quality
Per-section summary:
markdown
undefined
问题：综述文章提及的内容与具有直接证据的机制研究被同等对待。
解决方案：为每个结论应用证据层级：
层级符号标准
T1★★★具有直接证据的机制研究
T2★★☆功能研究（敲降、过表达）
T3★☆☆关联研究（筛选结果、GWAS、相关性分析）
T4☆☆☆提及类内容（综述、文本挖掘、外围研究）
报告中的示例：
markdown
ATP6V1A驱动溶酶体酸化 [★★★: PMID:12345678]，且与癌症进展相关 [★☆☆: PMID:23456789, TCGA表达数据]。
需标注证据等级的位置：
  1. 执行摘要 - 核心疾病结论
  2. 疾病关联 - 每个疾病关联项
  3. 关键论文表 - 证据层级列
  4. 建议 - 参考证据质量
分章节总结：
markdown
undefined

Theme: Lysosomal Function (47 papers)

主题：溶酶体功能（47篇论文）

Evidence Quality: Strong (32 mechanistic, 11 functional, 4 association)
undefined
证据质量：强（32篇机制研究、11篇功能研究、4篇关联研究）
undefined

7. Quantified Completeness (Not Just Categorical)

7. 量化完整性（而非仅分类）

Problem: "Include PPIs" is aspirational; reports pass the checklist but are data-thin.
Solution: Define numeric minimums for each section:
SectionMinimum DataIf Not Met
PPIs≥20 interactorsExplain why fewer + which tools failed
ExpressionTop 10 tissues with valuesNote "limited data" with specific gaps
DiseaseTop 10 associations with scoresNote if fewer available
VariantsAll 4 constraint scores (pLI, LOEUF, missense Z, pRec)Note which unavailable
DruggabilityAll modalities assessed"No drugs/probes" is valid data
LiteratureTotal + 5-year trend + 3-5 key papersNote if sparse (<50 papers)
Why this matters: Quantified minimums make completeness auditing objective and mechanical, not subjective.
问题：“包含蛋白质相互作用（PPIs）”这类要求较为空泛，报告虽符合检查清单但数据量不足。
解决方案：为每个章节定义数值最小值：
章节最小数据要求未达标时处理方式
PPIs≥20个相互作用因子说明数量较少的原因 + 失效的工具
表达数据前10个组织的具体数值标注“数据有限”并说明具体空白
疾病关联前10个带评分的关联项标注可用关联项数量不足
变异全部4种约束评分（pLI、LOEUF、错义Z值、pRec）标注缺失的评分项
可成药性评估所有成药模态“无药物/探针”属于有效数据
文献总数量 + 5年趋势 + 3-5篇关键论文标注文献稀疏（<50篇）
重要性：量化最小值使完整性审核客观、可量化，而非主观判断。

8. Mandatory Completeness Checklist

8. 强制完整性检查清单

Problem: Reports have inconsistent sections; some topics get skipped entirely.
Solution: Define mandatory sections that MUST exist, even if populated with "Limited evidence" or "Unknown":
markdown
undefined
问题：报告章节不一致，部分主题被完全跳过。
解决方案：定义必须包含的章节，即使内容为“证据有限”或“未知”：
markdown
undefined

Completeness Checklist (ALL Required)

完整性检查清单（所有项必填）

Identity & Context

身份与背景

  • Official identifiers resolved (all 6 types)
  • Synonyms/aliases documented
  • Naming collisions handled (or "none detected")
  • 已解析所有6类官方标识符
  • 已记录同义词/别名
  • 已处理命名冲突（或“未检测到冲突”）

Biology

生物学信息

  • Protein architecture (or "N/A for non-protein")
  • Subcellular localization
  • Expression profile (≥10 tissues with values)
  • Pathway involvement (≥10 pathways)
  • 蛋白结构（或“非蛋白类不适用”）
  • 亚细胞定位
  • 表达谱（≥10个组织的具体数值）
  • 通路参与情况（≥10条通路）

Mechanism

作用机制

  • Core function with evidence grades
  • Model organism data (or "none found")
  • Key assays described
  • 核心功能及证据等级
  • 模式生物数据（或“未找到相关数据”）
  • 关键实验方法描述

Disease & Clinical

疾病与临床

  • Genetic variants (SNVs and CNVs separated)
  • Constraint scores (all 4, with interpretations)
  • Disease links with evidence grades (≥10 or "limited")
  • 遗传变异（SNV与CNV分开记录）
  • 约束评分（全部4项及解读）
  • 疾病关联及证据等级（≥10个或“数量有限”）

Druggability

可成药性

  • Tractability for all modalities
  • Known drugs (or "none")
  • Chemical probes (or "none available")
  • Clinical pipeline (or "none")
  • 所有成药模态评估
  • 已知药物（或“无”）
  • 化学探针（或“无可用探针”）
  • 临床管线（或“无”）

Synthesis (CRITICAL)

合成总结（关键项）

  • Research themes (≥3 papers each, or "limited")
  • Open questions/gaps
  • Biological model synthesized
  • Testable hypotheses (≥3)
undefined
  • 研究主题（每个主题≥3篇论文或“数量有限”）
  • 未解决问题/数据空白
  • 生物学模型合成
  • 可验证假设（≥3个）
undefined

9. Aggregated Data Gaps Section

9. 数据空白汇总章节

Problem: "No data" notes scattered across 14 sections; users can't quickly see what's missing.
Solution: Add a dedicated Data Gaps & Limitations section that consolidates all gaps:
markdown
undefined
问题：“无数据”的说明分散在14个章节中，用户无法快速了解缺失内容。
解决方案：添加专门的数据空白与局限性章节，汇总所有空白：
markdown
undefined

15. Data Gaps & Limitations

15. 数据空白与局限性

SectionExpected DataActualReasonAlternative Source
6. PPIs≥20 interactors8Novel target, limited studiesLiterature review needed
7. ExpressionGTEx TPMNoneVersioned ID not recognizedSee HPA data
9. ProbesChemical probesNoneNo validated probes existConsider tool compound dev
Recommendations for Data Gaps:
  1. For PPIs: Query BioGRID with broader parameters; check yeast-2-hybrid studies
  2. For Expression: Query GEO directly for tissue-specific datasets

**Why this matters**: Users can quickly assess data quality and know where to look for more information.
章节预期数据实际情况原因替代数据源
6. PPIs≥20个相互作用因子8个靶点较新，相关研究有限需要开展文献综述
7. 表达数据GTEx TPM值无版本化ID未被识别查看HPA数据
9. 探针化学探针无无经过验证的探针考虑工具化合物开发
数据空白建议：
  1. 针对PPIs：使用更宽泛的参数查询BioGRID；检查酵母双杂交研究
  2. 针对表达数据：直接查询GEO获取组织特异性数据集

**重要性**：用户可快速评估数据质量，并知道从何处获取更多信息。

10. Query Strategy Optimization

10. 查询策略优化

Problem: Simple keyword searches retrieve too much noise or miss relevant papers.
Solution: Three-step collision-aware query strategy:
markdown
undefined
问题：简单的关键词检索会返回过多冗余结果，或遗漏相关论文。
解决方案：三步式冲突感知查询策略：
markdown
undefined

Query Strategy

查询策略

Step 1: High-Precision Seeds

步骤1：高精度种子集

Build a mechanistic core set (15-30 papers):
  • "[GENE_SYMBOL]"[Title] AND mechanism
  • "[FULL_PROTEIN_NAME]"[Title]
  • "UniProt:ACCESSION"
构建机制研究核心数据集（15-30篇论文）：
  • "[基因符号]"[标题] AND mechanism
  • "[完整蛋白名称]"[标题]
  • "UniProt:登录号"

Step 2: Citation Network Expansion

步骤2：引用网络扩展

From seeds, expand via citations:
  • Forward: PubMed_get_cited_by, EuropePMC_get_citations
  • Related: PubMed_get_related
  • Backward: EuropePMC_get_references
从种子集出发，通过引用关系扩展：
  • 正向引用：PubMed_get_cited_by、EuropePMC_get_citations
  • 相关论文：PubMed_get_related
  • 反向引用：EuropePMC_get_references

Step 3: Collision-Filtered Broad

步骤3：冲突过滤后的宽泛检索

Apply negative filters for known collisions:
  • "TRAG" AND immune NOT plasmid NOT conjugation
  • "JAK" AND kinase NOT "just another"

**Citation-first for sparse targets**: When keyword search returns <30 papers, prioritize citation expansion from the few good seeds.
应用已知冲突的负面过滤条件：
  • "TRAG" AND immune NOT plasmid NOT conjugation
  • "JAK" AND kinase NOT "just another"

**稀疏靶点优先引用扩展**：当关键词检索返回<30篇论文时，优先从少量优质种子集扩展引用关系。

11. Tool Failure Handling

11. 工具失效处理

Problem: NCBI elink and other APIs can be flaky; skills fail silently.
Solution: Automatic retry with fallback chains:
markdown
undefined
问题：NCBI elink等API可能不稳定，导致技能静默失败。
解决方案：自动重试及 fallback 链：
markdown
undefined

Failure Handling

失效处理

Retry Protocol

重试协议

Attempt 1 → fails → wait 2s → Attempt 2 → fails → wait 5s → Fallback
尝试1次 → 失败 → 等待2秒 → 尝试2次 → 失败 → 等待5秒 → 启用fallback

Fallback Chains

Fallback链

PrimaryFallback 1Fallback 2
PubMed_get_cited_byEuropePMC_get_citationsOpenAlex citations
PubMed_get_relatedSemanticScholarKeyword search
GTEx_*HPA_*Note as unavailable
UnpaywallEuropePMC OA flagOpenAlex is_oa
ChEMBL_get_target_activitiesGtoPdb_get_target_ligandsOpenTargets drugs
intact_get_interactionsSTRING_get_protein_interactionsOpenTargets interactions
主工具Fallback工具1Fallback工具2
PubMed_get_cited_byEuropePMC_get_citationsOpenAlex citations
PubMed_get_relatedSemanticScholar关键词检索
GTEx_*HPA_*标注为不可用
UnpaywallEuropePMC OA flagOpenAlex is_oa
ChEMBL_get_target_activitiesGtoPdb_get_target_ligandsOpenTargets drugs
intact_get_interactionsSTRING_get_protein_interactionsOpenTargets interactions

Document Failures

失效记录

In report: "Expression data unavailable (GTEx API timeout after 3 attempts)"

**Rule**: NEVER silently skip failed tools. Always document in the Data Gaps section.
在报告中注明：“表达数据不可用（GTEx API超时，已尝试3次）”

**规则**：绝不能静默跳过失效工具，必须在数据空白章节中记录。

12. Scalable Output Structure

12. 可扩展输出结构

Problem: Reports with 500+ papers become unreadable; users can't find what they need.
Solution: Separate narrative from data:
Narrative report (~20-50 pages max):
  • Executive summary
  • Key findings by theme
  • Top 20-50 papers highlighted
  • Conclusions and hypotheses
Bibliography files (unlimited):
  • [topic]_bibliography.json
    - Full structured data
  • [topic]_bibliography.csv
    - Tabular for filtering
JSON structure:
json
{
  "pmid": "12345678",
  "doi": "10.1038/xxx",
  "title": "...",
  "evidence_tier": "T1",
  "themes": ["lysosomal_function", "autophagy"],
  "is_core_seed": true,
  "oa_status": "gold"
}
问题：包含500+篇论文的报告可读性差，用户难以找到所需内容。
解决方案：将叙事内容与数据分离：
叙事报告（最多20-50页）：
  • 执行摘要
  • 按主题分类的关键发现
  • 重点突出20-50篇核心论文
  • 结论与假设
参考文献文件（无页数限制）：
  • [topic]_bibliography.json
    - 完整结构化数据
  • [topic]_bibliography.csv
    - 表格格式便于筛选
JSON结构：
json
{
  "pmid": "12345678",
  "doi": "10.1038/xxx",
  "title": "...",
  "evidence_tier": "T1",
  "themes": ["lysosomal_function", "autophagy"],
  "is_core_seed": true,
  "oa_status": "gold"
}

13. Synthesis Sections

13. 合成总结章节

Problem: Reports describe what was found but don't synthesize into actionable insights.
Solution: Require synthesis sections:
markdown
undefined
问题：报告仅描述发现内容，未提炼为可操作的见解。
解决方案：要求包含合成总结章节：
markdown
undefined

Required Synthesis Sections

必备合成总结章节

Biological Model (3-5 paragraphs)

生物学模型（3-5段）

Integrate all evidence into a coherent model:
  • What does the target do?
  • How does it connect to disease?
  • What's the key uncertainty?
整合所有证据，构建连贯模型：
  • 靶点的功能是什么？
  • 它如何与疾病关联？
  • 核心不确定性是什么？

Testable Hypotheses (≥3)

可验证假设（≥3个）

#HypothesisPerturbationReadoutExpected
1[Hypothesis][Experiment][Measure][Prediction]
#假设扰动方式检测指标预期结果
1[假设内容][实验方法][测量指标][预测结果]

Suggested Experiments

建议实验

Brief description of how to test each hypothesis.

---
简要描述验证每个假设的实验方法。

---

Skill Review Checklist

技能审核检查清单

When reviewing a ToolUniverse skill, check:
审核ToolUniverse技能时，需检查以下内容：

Tool Contract

工具协议

  • Tool parameters verified via 
    get_tool_info()
    or documented corrections
  • Versioned vs unversioned ID handling specified
  • Foundation data source identified (if available for domain)
  • 工具参数已通过
    get_tool_info()
    验证，或已记录修正内容
  • 已指定版本化与非版本化ID的处理方式
  • 已确定基础数据源（若领域存在）

Report Quality

报告质量

  • Report focuses on content, not search process
  • Methodology in separate appendix (optional)
  • Evidence grades applied to claims (T1-T4)
  • Source attribution on every fact
  • Sections exist even if "limited evidence"
  • 报告聚焦于内容，而非搜索流程
  • 方法论单独放在附录中（可选）
  • 结论已应用T1-T4证据等级
  • 每个事实都有来源归因
  • 即使“证据有限”，章节仍存在

Query Strategy

查询策略

  • Disambiguation phase before search
  • Collision detection for ambiguous names
  • High-precision seeds before broad search
  • Citation expansion option for sparse topics
  • Negative filters documented
  • 检索前已添加消歧阶段
  • 已检测模糊名称的冲突
  • 宽泛检索前已构建高精度种子集
  • 针对稀疏靶点提供引用扩展选项
  • 已记录负面过滤条件

Tool Usage

工具使用

  • Annotation tools used (not just literature)
  • Fallback chains defined
  • Failure handling with retry
  • OA handling (full or best-effort)
  • 使用了注释工具（而非仅依赖文献）
  • 已定义fallback链
  • 失效处理包含重试机制
  • 已处理开放获取（OA）内容（完整或最大努力）

Completeness

完整性

  • Quantified minimums defined per section
  • Completeness checklist with checkboxes
  • Data Gaps section aggregates all missing data
  • "Negative results" explicitly documented ("no probes" not blank)
  • 每个章节已定义量化最小值
  • 完整性检查清单包含复选框
  • 数据空白章节汇总了所有缺失数据
  • “阴性结果”已明确记录（“无探针”而非空白）

Output Structure

输出结构

  • Main report is narrative-focused
  • Bibliography in separate JSON/CSV
  • Synthesis sections required
  • 主报告以叙事为主
  • 参考文献单独放在JSON/CSV文件中
  • 要求包含合成总结章节

User Experience

用户体验

  • Progress updates are brief
  • No raw tool outputs shown
  • Final report is the deliverable
  • 进度更新简洁
  • 未显示原始工具输出
  • 最终报告为交付成果

Common Anti-Patterns to Fix

需修正的常见反模式

1. "Search Log" Reports

1. “检索日志”式报告

Bad: "Round 1: Searched PubMed (234 papers), OpenAlex (456 papers)..." Fix: Keep methodology internal; report findings only
错误示例：“第1轮：检索PubMed（234篇论文）、OpenAlex（456篇论文）...” 修正方案：方法论内部留存，仅报告研究发现

2. Missing Disambiguation

2. 缺失消歧步骤

Bad: Search "JAK" and get kinase + "just another kinase" papers mixed Fix: Add collision detection; build negative filters
错误示例：检索“JAK”，激酶相关论文与“just another kinase”相关论文混杂 修正方案：添加冲突检测；构建负面过滤条件

3. No Evidence Grading

3. 无证据分级

Bad: "Multiple studies show..." (which studies? what quality?) Fix: Apply T1-T4 grades; label each claim
错误示例：“多项研究表明...”（未说明研究来源、质量） 修正方案：应用T1-T4等级；为每个结论标注等级

4. Empty Sections Omitted

4. 省略空章节

Bad: Skip "Pathogen Involvement" because nothing found Fix: Include section with "None identified in literature search"
错误示例：因未找到相关内容，跳过“病原体参与”章节 修正方案：保留章节，内容为“文献检索未发现相关内容”

5. No Synthesis

5. 无合成总结

Bad: Long list of papers organized by theme Fix: Add biological model + testable hypotheses
错误示例：按主题罗列大量论文 修正方案：添加生物学模型 + 可验证假设

6. Monolithic Bibliography

6. 单一参考文献列表

Bad: 200 papers embedded in report narrative Fix: Top 20-50 in report; full list in JSON/CSV
错误示例：200篇论文嵌入报告叙事中 修正方案：报告中突出20-50篇核心论文；完整列表放在JSON/CSV文件中

7. Silent Failures

7. 静默失败

Bad: "Expression data: [blank]" (tool failed, user doesn't know) Fix: "Expression data unavailable (API timeout); see HPA directly"
错误示例：“表达数据：[空白]”（工具失效，用户不知情） 修正方案：“表达数据不可用（API超时）；请直接查看HPA数据”

8. Wrong Tool Parameters (NEW)

8. 错误的工具参数（新增）

Bad: 
Reactome_map_uniprot_to_pathways(uniprot_id=...)
returns empty Fix: Verify params via 
get_tool_info()
; use correct param 
id
错误示例：
Reactome_map_uniprot_to_pathways(uniprot_id=...)
返回空结果 修正方案：通过
get_tool_info()
验证参数；使用正确参数
id

9. Missing Versioned IDs (NEW)

9. 缺失版本化ID（新增）

Bad: GTEx returns empty for 
ENSG00000123456
Fix: Try versioned ID 
ENSG00000123456.12
; document which worked
错误示例：GTEx对
ENSG00000123456
返回空结果 修正方案：尝试版本化ID
ENSG00000123456.12
；记录有效的格式

10. No Foundation Layer (NEW)

10. 缺失基础数据层（新增）

Bad: Query 15 specialized tools independently, miss data when some fail Fix: Query comprehensive aggregator (e.g., Open Targets) first
错误示例：独立查询15个专用工具，部分工具失效时遗漏数据 修正方案：优先查询综合聚合器（如针对靶点的Open Targets）

11. Scattered "No Data" Notes (NEW)

11. “无数据”说明分散（新增）

Bad: "No data" in 5 different sections; user doesn't know overall gaps Fix: Aggregate all gaps in dedicated Data Gaps section with recommendations
错误示例：5个不同章节中出现“无数据”；用户无法了解整体空白情况 修正方案：在专门的数据空白章节汇总所有缺失内容，并提供建议

12. Aspirational Completeness (NEW)

12. 空泛的完整性要求（新增）

Bad: "Include PPIs" ✓ (but only 3 interactors listed) Fix: "≥20 PPIs OR explanation why fewer"
错误示例：“包含PPIs” ✓（但仅列出3个相互作用因子） 修正方案：“≥20个PPIs 或说明数量较少的原因”

Template: Optimized Skill Structure

模板：优化后的技能结构

markdown
---
name: [domain]-research
description: [What it does]. Creates detailed report with evidence grading 
and mandatory completeness. [When to use triggers].
---
markdown
---
name: [domain]-research
description: [技能功能]。生成带有证据分级和强制完整性检查的详尽报告。[触发场景]。
---

[Domain] Research Strategy

[领域]研究策略

When to Use

适用场景

[Trigger scenarios]
[触发场景]

Workflow

工作流

Phase -1: Tool Verification → Phase 0: Foundation Data → Phase 1: Disambiguate → Phase 2: Search → Phase 3: Report
阶段-1：工具验证 → 阶段0：基础数据 → 阶段1：消歧 → 阶段2：检索 → 阶段3：报告

Phase -1: Tool Verification

阶段-1：工具验证

[Parameter corrections table for tools used in this skill]
[本技能所用工具的参数修正表]

Phase 0: Foundation Data

阶段0：基础数据

[Comprehensive aggregator query - e.g., Open Targets for targets]
[综合聚合器查询 - 如针对靶点的Open Targets]

Phase 1: Disambiguation (Default ON)

阶段1：消歧（默认开启）

[ID resolution (versioned + unversioned), collision detection, baseline profile]
[ID解析（版本化 + 非版本化）、冲突检测、基准概况]

Phase 2: Specialized Queries (Internal)

阶段2：专用查询（内部）

[Query strategy with collision filters, citation expansion, tool fallbacks]
[带有冲突过滤、引用扩展、工具fallback的查询策略]

Phase 3: Report Synthesis

阶段3：报告合成

[Progressive writing, evidence grading, mandatory sections]
[渐进式撰写、证据分级、强制章节]

Output Files

输出文件

  • [topic]_report.md
    (narrative, always)
  • [topic]_bibliography.json
    (data, always)
  • methods_appendix.md
    (only if requested)
  • [topic]_report.md
    （叙事性，始终输出）
  • [topic]_bibliography.json
    （数据，始终输出）
  • methods_appendix.md
    （仅在请求时输出）

Quantified Minimums

量化最小值

[Specific numbers per section - e.g., ≥20 PPIs, top 10 tissues]
[各章节具体数值要求 - 如≥20个PPIs、前10个组织]

Completeness Checklist

完整性检查清单

[ALL required sections with checkboxes]
[所有必填章节及复选框]

Data Gaps Section

数据空白章节

[Template for aggregating missing data with recommendations]
[汇总缺失数据的模板及建议]

Evidence Grading

证据分级

[T1-T4 definitions with required locations]
[T1-T4定义及必填标注位置]

Tool Reference

工具参考

[Tools by category with fallback chains and parameter notes]

---
[按分类列出工具，包含fallback链及参数说明]

---

Quick Fixes for Common Complaints

常见用户反馈快速修复方案

User ComplaintRoot CauseFix
"Report is too short"Missing annotation dataAdd Phase 1 disambiguation + Phase 0 foundation
"Too much noise"No collision filteringAdd negative query filters
"Can't tell what's important"No evidence gradingAdd T1-T4 tiers
"Missing sections"No completeness checklistAdd mandatory sections with minimums
"Too long/unreadable"Monolithic outputSeparate narrative from JSON
"Just a list of papers"No synthesisAdd biological model + hypotheses
"Shows search process"Wrong output focusReport-only; methodology in appendix
"Tool failed, no data"No fallback handlingAdd retry + fallback chains
"Empty results, no error"Wrong tool parametersAdd Phase -1 param verification
"GTEx returns nothing"Versioned ID neededTry 
ENSG*.version
format
"Data seems incomplete"No foundation layerAdd Phase 0 with aggregator
"Can't tell what's missing"Scattered gapsAdd Data Gaps section
用户反馈根本原因修复方案
“报告太短”缺失注释数据添加阶段1消歧 + 阶段0基础数据
“冗余内容太多”无冲突过滤添加负面查询过滤条件
“无法区分重要内容”无证据分级添加T1-T4层级
“缺失章节”无完整性检查清单添加带最小值要求的强制章节
“太长/可读性差”单一输出结构将叙事内容与JSON数据分离
“只是论文列表”无合成总结添加生物学模型 + 假设
“显示检索流程”输出焦点错误仅报告内容；方法论放在附录
“工具失效，无数据”无fallback处理添加重试 + fallback链
“空结果，无错误提示”工具参数错误添加阶段-1参数验证
“GTEx无返回结果”需要版本化ID尝试
ENSG*.version
格式
“数据不完整”缺失基础数据层添加阶段0聚合器查询
“无法了解缺失内容”空白说明分散添加数据空白章节

Summary

总结

Seven pillars of optimized ToolUniverse skills:
  1. Verify tool contracts - Check params via 
    get_tool_info()
    ; maintain corrections table
  2. Foundation first - Query comprehensive aggregators before specialized tools
  3. Disambiguate carefully - Resolve IDs (versioned + unversioned), detect collisions, get baseline from annotation DBs
  4. Grade evidence - T1-T4 tiers on all claims; summarize quality per section
  5. Require quantified completeness - Numeric minimums, not just "include X"
  6. Report content, not process - Methodology in appendix only if asked; aggregate gaps in one section
  7. Synthesize - Biological models and testable hypotheses, not just paper lists
Apply these principles to any ToolUniverse research skill for better user experience and actionable output.
优化ToolUniverse技能的七大支柱：
  1. 验证工具协议 - 通过
    get_tool_info()
    检查参数；维护修正表
  2. 优先基础数据 - 调用专用工具前先查询综合聚合器
  3. 仔细消歧 - 解析ID（版本化 + 非版本化）、检测冲突、从注释数据库获取基准数据
  4. 证据分级 - 为所有结论应用T1-T4层级；分章节总结证据质量
  5. 强制量化完整性 - 定义数值最小值，而非仅“包含X”
  6. 报告内容而非流程 - 方法论仅在附录中提供；在一个章节汇总所有空白
  7. 合成总结 - 构建生物学模型与可验证假设，而非仅罗列论文
将这些原则应用于任意ToolUniverse研究技能，可提升用户体验并生成可操作的输出结果。