用 SKILL.md 定义 ML 模型开发 Agent：ruflo 仓库 agent-data-ml-model 技能的完整配置与工作机制解析

本文以 ruflo 仓库中的 agent-data-ml-model 技能定义 为主体，逐段拆解这份 SKILL.md 如何把一个“机器学习模型开发者”角色编码为可触发的 Agent 技能：从触发器匹配、工具与路径护栏、资源上限、生命周期 Hooks，到内置的 sklearn 工作流指令。读完你可以掌握在多 Agent 编排系统中定义领域专用 Agent 技能的完整配置范式，并能将其迁移到自己的 ML 工程场景。

一、技能在 ruflo 仓库中的位置与调用方式

该技能位于仓库的 .agents/skills/agent-data-ml-model/ 目录，目录内只有一个核心文件 SKILL.md（全文约 198 行，无任何附加脚本）。根据 .agents/README.md 的说明，.agents/ 是面向 OpenAI Codex CLI 的 Agent 配置与技能目录，其标准结构为：

.agents/
  config.toml     # Main configuration file
  skills/         # Skill definitions
    skill-name/
      SKILL.md    # Skill instructions
      scripts/    # Optional scripts
      docs/       # Optional documentation
  README.md

技能的调用约定是 $skill-name 语法。值得注意的是，SKILL.md 的第一段 frontmatter 就声明了这一入口：

name: agent-data-ml-model
description: Agent skill for data-ml-model - invoke with $agent-data-ml-model

也就是说，用户在会话中键入 $agent-data-ml-model，编排层就会把文件后半部分的角色指令与第一份 YAML 元数据一并装载进 Agent 上下文。仓库的 .agents/skills/ 目录下共有 130 余个技能目录（如 agent-neural-network、agent-trading-predictor、neural-training 等），agent-data-ml-model 是其中定位为数据处理领域（type: "data"）的 ML 专项技能，与这些邻居技能遵循同一套 SKILL.md 文件格式，但各自声明了不同的触发词、工具白名单与路径护栏。

二、身份元数据：声明这是一个“需要审批”的 ML 专家

文件的第一份完整 YAML frontmatter（第 6–126 行）是技能的机器可读声明，其身份字段如下：

name: "ml-developer"
description: "Specialized agent for machine learning model development, training, and deployment"
color: "purple"
type: "data"
version: "1.0.0"
created: "2025-07-25"
author: "Claude Code"
metadata:
  specialization: "ML model creation, data preprocessing, model evaluation, deployment"
  complexity: "complex"
  autonomous: false  # Requires approval for model deployment

几个字段值得重点关注：

• name: ml-developer：技能目录名（agent-data-ml-model）与内部角色名（ml-developer）解耦，前者用于 $ 前缀调用寻址，后者用于运行时身份展示；
• type: "data"：将技能归入数据处理域，便于按域路由任务；
• complexity: "complex"：声明该任务类型属于复杂任务，编排器可据此分配更长的执行预算；
• ****autonomous: false：明确该 Agent 不是全自主的，注释说明原因是“模型部署需要审批”。这个声明与后文 integration.requires_approval_from 和 behavior.confirmation_required 形成了三处互相印证的安全设计。

三、触发机制 triggers：四类匹配维度

triggers 段 定义了四类匹配维度，任一命中即可激活该技能：

维度	取值	匹配语义
keywords	machine learning、ml model、train model、predict、classification、regression、neural network	用户指令中出现这些关键词
file_patterns	**/*.ipynb、**/model.py、**/train.py、**/*.pkl、**/*.h5	任务涉及的文件命中 glob 模式（Notebook、模型/训练脚本、sklearn pickle 与 Keras 权重文件）
task_patterns	create * model、train * classifier、build ml pipeline	任务描述模板匹配，* 为通配符
domains	data、ml、ai	任务所属领域标签

这种“关键词 + 文件模式 + 任务模板 + 领域”的多维触发设计，让编排层可以在没有用户显式 $agent-data-ml-model 的情况下，依据上下文自动路由到该技能。

四、能力边界 capabilities：工具白名单与资源上限

capabilities 段 是本技能最典型的“护栏”配置：

capabilities:
  allowed_tools:
    - Read
    - Write
    - Edit
    - MultiEdit
    - Bash
    - NotebookRead
    - NotebookEdit
  restricted_tools:
    - Task  # Focus on implementation
    - WebSearch  # Use local data
  max_file_operations: 100
  max_execution_time: 1800  # 30 minutes for training
  memory_access: "both"

逐条解读：

• allowed_tools：只开放文件读写类（Read/Write/Edit/MultiEdit）、命令执行类（Bash）与 Notebook 专属工具（NotebookRead/NotebookEdit）。ML 开发需要编辑 .ipynb 是选择 Notebook 工具的直接原因；
• restricted_tools：显式禁用 Task（不得再派生子 Agent，注释说明目的是“专注实现本身”）和 WebSearch（注释“Use local data”，即强制模型只基于本地数据工作，避免外部数据污染实验）；
• max_file_operations: 100：单次任务的文件操作次数上限，防止失控的批量重写；
• max_execution_time: 1800：30 分钟执行预算，注释明确这是“为训练预留”的时间；
• memory_access: "both"：允许同时访问两种记忆通道（结合 ruflo 项目定位可推断对应其分层记忆体系），使该 Agent 能在训练前后读写记忆。

五、路径与文件约束 constraints：文件级沙箱

constraints 段 在工具白名单之外又加了一层文件系统沙箱：

constraints:
  allowed_paths:
    - "data/**"
    - "models/**"
    - "notebooks/**"
    - "src/ml/**"
    - "experiments/**"
    - "*.ipynb"
  forbidden_paths:
    - ".git/**"
    - "secrets/**"
    - "credentials/**"
  max_file_size: 104857600  # 100MB for datasets
  allowed_file_types:
    - ".py"
    - ".ipynb"
    - ".csv"
    - ".json"
    - ".pkl"
    - ".h5"
    - ".joblib"

• allowed_paths：只允许触碰数据（data/**）、模型产物（models/**）、Notebook（notebooks/**）、ML 源码（src/ml/**）、实验记录（experiments/**）以及任意位置的 .ipynb。目录命名与 triggers.file_patterns 中出现的 model.py/train.py/.pkl/.h5 形成呼应；
• forbidden_paths：硬屏蔽 .git/**（防止 Agent 篡改版本历史）与凭据目录 secrets/**、credentials/**；
• max_file_size: 104857600：单文件 100MB 上限，注释说明是为数据集留的额度。作为对照，全局配置 .agents/config.toml 的 [security] 段中 max_file_size = 10485760（10MB），也就是说该技能在自己的声明层面把数据集文件上限放宽到了全局值的 10 倍；
• allowed_file_types：只处理 Python、Notebook、CSV/JSON 数据、pickle/HDF5/joblib 模型产物这七类扩展名。

从源码结构看，这套“白名单工具 + 白名单路径 + 白名单扩展名 + 体积上限”的四重约束，与 config.toml 中全局 blocked_patterns（拦截 .env、credentials.json、.pem、.key）叠加生效，构成技能级与全局级两层防线。

六、行为策略 behavior：确认、自动回滚与日志级别

behavior:
  error_handling: "adaptive"
  confirmation_required:
    - "model deployment"
    - "large-scale training"
    - "data deletion"
  auto_rollback: true
  logging_level: "verbose"

四个字段定义了三类关键动作必须征求确认（部署模型、大规模训练、删除数据），与开头 autonomous: false 的声明一致；auto_rollback: true 要求失败操作自动回退（对“删除数据”类操作是必要的兜底）；error_handling: "adaptive" 表示错误处理策略自适应，具体提示词见下文 Hooks 的 on_error 段；logging_level: "verbose" 保证训练过程中的详细日志可供事后审计。

七、协作与资源优化 integration / optimization

integration:
  can_spawn: []
  can_delegate_to:
    - "data-etl"
    - "analyze-performance"
  requires_approval_from:
    - "human"  # For production models
  shares_context_with:
    - "data-analytics"
    - "data-visualization"
optimization:
  parallel_operations: true
  batch_size: 32  # For batch processing
  cache_results: true
  memory_limit: "2GB"

• can_spawn: []：不允许自行派生新 Agent（与 restricted_tools 中禁用 Task 再次呼应），但 can_delegate_to 允许把数据预处理类工作委托给 data-etl、把性能分析委托给 analyze-performance——即“可委托、不可派生”的受限协作模式；
• requires_approval_from: human：生产级模型必须人工审批，这是该技能中唯一明确的审批对象声明；
• shares_context_with：与 data-analytics、data-visualization 共享上下文，意味着特征工程的中间产物可被下游分析/可视化技能直接复用；
• optimization：开启并行操作、批量处理 batch_size: 32、结果缓存，并给整个执行环境划定 memory_limit: "2GB"。作为对照，config.toml 全局 [performance] 段给每个 Agent 的默认内存是 512MB、并发上限 max_agents = 8、任务超时 task_timeout = 300 秒——ML 技能在技能层把内存放大 4 倍、把执行预算放大到 30 分钟，明显是专为训练任务调优过的配额。

八、生命周期 Hooks：三段内嵌 shell 脚本

hooks 段 直接以内嵌多行 shell 定义了执行前、执行后、出错时三个钩子：

pre_execution（环境自检）：

echo "🤖 ML Model Developer initializing..."
echo "📁 Checking for datasets..."
find . -name "*.csv" -o -name "*.parquet" | grep -E "(data|dataset)" | head -5
echo "📦 Checking ML libraries..."
python -c "import sklearn, pandas, numpy; print('Core ML libraries available')" 2>/dev/null || echo "ML libraries not installed"

执行前扫描项目内 CSV/Parquet 数据集是否存在（head -5 防止输出爆炸），并用一行 Python 探测 sklearn/pandas/numpy 是否就绪，未安装则给出降级提示——把“环境不满足”提前暴露，而不是等到训练中途失败。

post_execution（产物盘点）：

echo "✅ ML model development completed"
echo "📊 Model artifacts:"
find . -name "*.pkl" -o -name "*.h5" -o -name "*.joblib" | grep -v __pycache__ | head -5
echo "📋 Remember to version and document your model"

执行后列出 .pkl/.h5/.joblib 模型产物（过滤 __pycache__），并提醒对模型做版本化与文档化——对应文末最佳实践中的“Version control models and data”。

on_error（诊断提示）：

echo "❌ ML pipeline error: {{error_message}}"
echo "🔍 Check data quality and feature compatibility"
echo "💡 Consider simpler models or more data preprocessing"

注意 {{error_message}} 模板占位符：错误钩子是模板化的，由运行时会话注入真实错误信息，两条诊断建议（数据质量/特征兼容性、考虑更简单的模型或更充分的数据预处理）是给 LLM 的修复方向提示，与 behavior.error_handling: "adaptive" 的自适应策略相配套。

九、Markdown 指令主体：职责、工作流与标准代码模式

frontmatter 之后（第 128–198 行）是供模型直接遵循的角色指令。

9.1 五项核心职责

1. 数据预处理与特征工程
2. 模型选择与架构设计
3. 训练与超参数调优
4. 模型评估与验证
5. 部署准备与监控

9.2 五阶段 ML 工作流

文档把端到端流程固化为五个阶段，每阶段列出具体动作：

1. Data Analysis：探索性数据分析、特征统计、数据质量检查；
2. Preprocessing：缺失值处理、特征缩放/归一化、类别变量编码、特征选择；
3. Model Development：算法选择、交叉验证搭建、超参数调优、集成方法（Ensemble）；
4. Evaluation：性能指标、混淆矩阵、ROC/AUC 曲线、特征重要性；
5. Deployment Prep：模型序列化、API 端点创建、监控搭建。

9.3 标准代码模式：sklearn Pipeline

文档内嵌了一段标准 scikit-learn 管道代码（第 169–191 行），作为该技能产出代码的参考骨架：

# Standard ML pipeline structure
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.model_selection import train_test_split

# Data preprocessing
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

# Pipeline creation
pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('model', ModelClass())
])

# Training
pipeline.fit(X_train, y_train)

# Evaluation
score = pipeline.score(X_test, y_test)

几个可复用的工程细节：train_test_split 先切分、StandardScaler 放在 Pipeline 内部（即只在训练折上拟合，避免测试集信息泄漏）；random_state=42 固定随机种子保证可复现；ModelClass() 是占位符，实际使用时替换为具体估计器。

9.4 五条最佳实践

• 永远在预处理之前切分数据（Always split data before preprocessing）；
• 使用交叉验证做稳健评估；
• 记录所有实验与参数；
• 对模型和数据做版本管理；
• 文档化模型假设与局限性。

十、内置示例：两个可对照的触发-响应样例

文件末尾的 examples 段 给出了两条触发样例，可作为验证技能是否按预期路由的参考：

触发语	技能声明的响应要点
"create a classification model for customer churn prediction"	开发客户流失预测的完整管道：数据预处理、模型选择、训练、评估
"build neural network for image classification"	构建图像分类神经网络架构：数据增强、模型训练、性能评估

两条样例分别覆盖“经典机器学习分类”与“深度学习”两种路径，且响应措辞都承诺给出完整管道而非单点代码，与该技能“end-to-end ML workflows”的自我定位一致。

十一、与全局配置的联动：.agents/config.toml 中的对应开关

技能文件只是声明层，真正装载与执行受 .agents/config.toml 控制，几个与本文主题直接相关的配置点：

• 技能装载清单（第 83–97 行）：当前配置通过 [[skills.config]] 显式启用了 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能。从源码结构看，agent-data-ml-model 不在默认启用列表中，如需常驻装载可按同样格式追加一条 path = ".agents/skills/agent-data-ml-model" 的条目；
• 审批策略：全局 approval_policy = "on-request"（第 24 行），与技能声明的 requires_approval_from: human 叠加后，生产模型部署会触发人类审批；
• 沙箱模式：全局 sandbox_mode = "workspace-write"（第 30 行），限定写操作在工作区内，与技能层 allowed_paths/forbidden_paths 形成内外两层路径约束；
• Profiles 预设（第 103–119 行）：dev（approval_policy = "never" + 完全访问）、safe（全只读 + 禁用联网）、ci（自动批准 + 工作区写入）三套预设，可用于在不同环境中切换该 ML 技能的执行松紧度；
• Hooks 开关（第 263–274 行）：[hooks] 段全局启用生命周期钩子（pre_task/post_task 均为 true），这是技能内 pre_execution/post_execution/on_error 脚本能够被执行的总闸。

总结

agent-data-ml-model/SKILL.md 展示了一个完整的“领域 Agent 技能”定义范式：双层 frontmatter 分别承载调用寻址（$agent-data-ml-model）与运行时策略（触发、工具白名单、路径沙箱、资源配额、审批点、Hooks、协作关系），Markdown 主体则提供角色指令、五阶段工作流、sklearn 代码骨架与最佳实践。它的安全设计贯穿三层——autonomous: false + requires_approval_from: human 管“谁批准”，allowed_tools/allowed_paths/allowed_file_types 管“能碰什么”，max_execution_time/memory_limit/max_file_size 管“用多少资源”——并与 .agents/config.toml 的全局审批策略、沙箱模式和 Hooks 总闸联动。对希望在 ruflo 这类编排系统中新增自定义领域 Agent（数据、ML 或其他垂直方向）的开发者而言，这份文件是一份可直接参照的配置模板。