菜单
Use when generating Markdown reports that explain RealAnalyst metadata, sync results, dataset registration details, field/metric/filter semantics, metadata gaps, or metadata inventory. Triggers: 元数据报告, 同步结果说明, 字段口径说明, 数据集注册报告, 元数据清单.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when: (1) Starting analysis to understand dataset structure, (2) Checking data quality before processing, (3) Need schema, semantic roles, null counts, and signals before analysis, (4) Need to bind a profiling result back to a specific CSV inside a continuous-analysis job. Triggers: profiling, 数据画像, 数据概览, profile, 数据质量, schema summary.
用于通用数据分析任务的总控编排与分析执行 skill。适用于监控、汇报、诊断、归因、对标、排名、探索、专项分析，以及任何需要连续对话、连续分析、单会话单 job 管理、先做需求画像、获得用户确认，再编排取数、数据体检、分析执行和报告追加流程的请求。
Controlled Tableau, DuckDB, MySQL, and ClickHouse data export for RealAnalyst/Codex. Use when an analysis task needs to fetch formal CSV data from a registered source in the unified SQLite registry, including Tableau view/domain exports with vf/vp filters and SQL table/view exports with field whitelist, filters, aggregation, and audited job metadata updates. Triggers: tableau export, duckdb export, mysql export, clickhouse export, 受控取数, 数据导出, 补数, 追加分析, export_summary, duckdb_export_summary, data_export_summary.
Use when analysis jobs, user feedback, profile outputs, or real-data probes need to be converted into reference materials for later RA:metadata maintenance; trigger for metadata 修正材料, 字段定义不清, 指标口径待修, evidence 补充, job feedback, profile-based metadata refinement.
Use when: (1) Need to search for metric, field, term, dataset, or mapping definitions from the metadata index, (2) Need to browse available datasets before starting analysis, (3) Need a lightweight lookup result instead of reading full YAML files. Triggers: 搜索指标, 搜索字段, 搜索术语, 搜索数据集, metadata search, 浏览数据集目录, catalog, dataset discovery.
Use when initializing, registering, refreshing, validating, or packaging LLM-maintained dataset metadata for RealAnalyst; trigger for 数据集注册, 元数据初始化, 业务口径维护, metadata context, Tableau/DuckDB source onboarding, or analysis planning context. For search/catalog use RA:metadata-search.
| name | RA:metadata-report |
| description | Use when generating Markdown reports that explain RealAnalyst metadata, sync results, dataset registration details, field/metric/filter semantics, metadata gaps, or metadata inventory. Triggers: 元数据报告, 同步结果说明, 字段口径说明, 数据集注册报告, 元数据清单. |
用于把 RealAnalyst 的元数据、连接器同步结果、数据源注册信息和待补齐项写成可复核的 Markdown 报告。它只负责“阐述元数据”，不负责注册数据集、取数分析或改写业务结论。
本 skill 是 dataset-first 元数据 Markdown 报告的唯一出口。报告统一通过 skills/metadata-report/scripts/generate_report.py 生成；主入口不要求用户提供 connector。正文按“元数据事实摘要 -> 数据集信息 -> 字段信息 -> 指标信息 -> 筛选、参数与取值信息 -> 映射与来源追溯 -> 未维护项 -> 运行与注册状态 -> 报告生成信息”组织。
使用本 skill：
不要使用本 skill：
RA:metadata。RA:analysis-run；仅高级手工编排或排障时由流程调用 RA:data-export。RA:report。RA:report-verify。报告只能基于真实元数据产物和脚本输出，禁止凭字段名想象业务含义。 字段和指标必须按通用结构处理：role、business_definition、expression、aggregation、mapping、dictionary、evidence 和 validate 状态。禁止为了某个具体业务字段名、指标名或固定中文列名写特例补丁。
优先级如下：
metadata/datasets/*.yaml：数据集说明、字段、指标、时间字段、粒度、适用边界。metadata/mappings/*.yaml：源字段到标准语义的映射和补齐状态。metadata/dictionaries/*.yaml：公共指标、维度、术语的业务定义。metadata/sources/：原始证据、用户文档、connector discovery 归档。runtime/registry.db：只说明运行时是否可取数、是否已维护筛选值或范围，不作为业务定义来源。metadata/index/search.db / JSONL index：作为检索层事实状态，不替代 dataset YAML。报告事实必须通过 skills/metadata/lib/metadata_facts.py / metadata.py read 这类统一读取能力进入报告层。report 脚本只做展示编排，不另起一套 broad YAML / registry parser。
优先使用统一报告生成脚本，不手写从零拼报告。
| 报告类型 | 脚本 | 默认输出目录 |
|---|---|---|
| 单数据集元数据报告 | skills/metadata-report/scripts/generate_report.py --dataset-id <dataset_id> | metadata/reports/<dataset_id>_metadata_report.md |
| 全部数据集元数据报告 | skills/metadata-report/scripts/generate_report.py --all | metadata/reports/ |
| 指定输出目录 | skills/metadata-report/scripts/generate_report.py --dataset-id <dataset_id> --output-dir <dir> | <dir>/<dataset_id>_metadata_report.md |
| connector 兼容报告 | skills/metadata-report/scripts/generate_report.py --connector <connector> ... | legacy compatibility only |
python3 {baseDir}/skills/metadata/scripts/metadata.py validate
python3 {baseDir}/skills/metadata/scripts/metadata.py inventory
python3 {baseDir}/skills/metadata/scripts/metadata.py status --dataset-id <dataset_id>
如果 validate 失败，报告必须把失败项写成“待修复问题”，不要把未通过校验的定义写成确定口径。
python3 {baseDir}/skills/metadata/scripts/metadata.py read --dataset-id <dataset_id>
python3 {baseDir}/skills/metadata-report/scripts/generate_report.py --dataset-id <dataset_id>
python3 {baseDir}/skills/metadata-report/scripts/generate_report.py --all
不要为了生成报告运行 RA:data-profile、读取 jobs/*/profile/*、现场查询 DuckDB 或现场采样。取值、范围、筛选器和参数只读取长期 metadata / runtime registry 已维护事实；没有就写“未维护”。
需要人工补写或审阅时，先读取：
{baseDir}/skills/metadata-report/references/report-template.md
该模板是脚本输出结构的目标写作版；脚本若仍输出旧结构，以模板作为后续改造目标，人工补写时优先遵循模板。
dataset-first 报告章节顺序固定：
## 1. 元数据事实摘要## 2. 数据集信息## 3. 字段信息## 4. 指标信息## 5. 筛选、参数与取值信息## 6. 映射与来源追溯## 7. 未维护项## 8. 运行与注册状态## 9. 报告生成信息没有真实内容的 section 不输出；缺失事实统一进入“未维护项”。表头、章节和状态标签用中文；metadata 原始值不翻译、不改写。
needs_review=true、review_required=true 或无证据项必须显式进入“未维护项”。filters 和 parameters 必须分开说明。--vf 筛选器和 --vp 参数；DuckDB 报告必须分清 sql_where 筛选器和字段/指标。schema_note，也不要生成“Schema 说明”列；字段存在性、DuckDB 类型、Tableau 字段名只能作为结构化类型或证据来源，不作为业务定义。*_metadata_context.json 伴生文件；agent 需要结构化读取时使用 RA:metadata 的 read/search/status。完成前检查：
| 误区 | 正确做法 |
|---|---|
| 只写“已同步成功” | 列清同步对象、字段、指标、筛选器、参数和待补齐项 |
| 用字段名猜业务定义 | 只读取 business_definition.text；找不到就标记待补齐 |
| 把元数据报告写成分析报告 | 只说明元数据能力和边界，不输出业务经营结论 |
把 schema_note 当业务说明展示 | 报告只展示 business_definition.text、定义位置和口径状态 |
| 忽略筛选器枚举值 | 可列举值、默认值、参数用法必须单独写 |
| 遇到 validate 失败仍继续写确定口径 | 报告降级为“元数据待修复报告”，失败项进入元数据补齐清单 |
元数据报告完成后，用下面结构向用户汇报，并按本次结果动态裁剪：
完成情况：
- 已生成报告类型：<元数据报告 / 注册说明 / 待补齐项报告>
- 报告输出路径：<path>
- 待补齐项：<needs_review / 校验失败项 / metadata gap 数量>
下一步建议：
- 最推荐下一步：/skill RA:analysis-run ...（metadata 和 registry 已准备好，准备正式分析）
- 可选下一步：/skill RA:metadata ...（需要修复待补齐项或维护 YAML）
- 可选下一步：/skill RA:metadata-refine ...（需要把分析反馈整理为修正材料）
边界提醒：
- 本 skill 只生成数据集长期口径说明或 gap 报告，没有修改正式 metadata。
- 报告内容必须来自真实 metadata、metadata search/read/status、runtime registry、mapping 或 dictionary evidence。