llama-agent-skills/openspec/changes/add-skill-support/design.md

Context

本项目是一个全新的 Python 项目（greenfield），目标是构建一个基于 LlamaIndex Workflow 的 Agent，能够动态加载和执行 SKILL。

当前状态：

• 项目仅有 src/llama_agent_skills/__init__.py 中一个空的 main() 入口
• 无任何现有依赖（pyproject.toml 的 dependencies = []）
• .opencode/skills/ 和 .github/skills/ 下有 4 个 SKILL.md 示例文件，定义了 SKILL 的标准格式

SKILL 格式（已有约定）：

• YAML frontmatter：name、description、license、metadata（author、version）
• Markdown 正文：自由格式的指令文本，包含 Steps、Guardrails、Input/Output 等段落

LlamaIndex Workflow 关键能力（调研结论）：

• Workflow 基类：事件驱动、@step 装饰器、Context 状态管理
• AgentWorkflow.from_tools_or_functions()：接受 tools 列表和 system_prompt
• FunctionAgent：支持 system_prompt、tools、can_handoff_to
• 工具列表存储为实例变量 self.tools，可运行时动态增删
• Context.set/get 提供步骤间状态共享

约束：

• 不引入 Shell/subprocess，纯 Python 运行
• 脚本类 SKILL 功能暂不支持
• 需要支持线上部署场景

Goals / Non-Goals

Goals:

• 实现 SKILL.md 文件的解析器，能提取 frontmatter 元数据和正文指令
• 实现 SKILL 注册表，支持从目录扫描、运行时动态注册/注销
• 构建基于 LlamaIndex Workflow 的核心 Agent，将 SKILL 作为 system prompt 的扩展注入
• 提供清晰的 Python API，方便程序化创建和运行 Agent
• 保持架构简洁，为后续扩展（MCP 工具、多 Agent 协作）留出空间

Non-Goals:

• 不实现 Shell/subprocess 执行能力（安全约束）
• 不实现 SKILL 内定义的脚本/命令执行功能
• 不实现多 Agent 协作/handoff（后续迭代）
• 不实现 SKILL 的远程加载（仅支持本地文件系统）
• 不实现 Web UI 或 REST API 层
• 不实现 MCP server/client 集成（后续迭代）

Decisions

D1: SKILL 注入方式 — System Prompt 拼接

决定： 将 SKILL 的 Markdown 正文作为 system prompt 的一部分注入 Agent。

备选方案：

• A) 将 SKILL 转换为 LlamaIndex BaseTool（每个 SKILL 变成一个可调用工具）
• B) 将 SKILL 注入 system prompt（当前选择）
• C) 将 SKILL 作为 RAG 文档，通过检索注入

选择 B 的理由：

• SKILL 本质是「行为指令」而非「可调用函数」，它定义了 Agent 应该如何行动，而不是提供一个新的能力入口
• System prompt 注入最自然，与 LlamaIndex 的 system_prompt 参数直接对应
• 方案 A 需要为每个 SKILL 包装一个工具入口，增加不必要的间接层
• 方案 C 引入 RAG 复杂度，对于有限数量的 SKILL 是过度设计
• 后续如果 SKILL 需要携带工具定义，可以在 SKILL 格式中扩展 tools 字段，注册为真正的工具

D2: SKILL.md 解析策略 — python-frontmatter 库

决定： 使用 python-frontmatter 库解析 SKILL.md 的 YAML frontmatter + Markdown body。

备选方案：

• A) 手写 YAML + Markdown 分割解析器
• B) 使用 python-frontmatter 库（当前选择）
• C) 使用 pyyaml + 手动分割 --- 分隔符

选择 B 的理由：

• python-frontmatter 是成熟的库，专门处理 frontmatter 格式，边界情况覆盖好
• 减少自研代码量和 bug 风险
• 自动处理 YAML 类型转换

D3: Agent 架构 — 基于 AgentWorkflow 的单 Agent

决定： 使用 AgentWorkflow.from_tools_or_functions() 构建单 Agent，通过 system_prompt 参数注入 SKILL 上下文。

备选方案：

• A) 自定义 Workflow 子类，手动实现所有步骤
• B) 使用 AgentWorkflow.from_tools_or_functions()（当前选择）
• C) 使用 FunctionAgent + 多 Agent 编排

选择 B 的理由：

• AgentWorkflow 提供开箱即用的对话循环、工具调用、流式输出
• 对于第一版，单 Agent 足够验证 SKILL 注入概念
• 如需自定义步骤（如 SKILL 热加载），可以后续继承扩展
• 方案 A 需要重写大量 LlamaIndex 已有逻辑
• 方案 C 在当前阶段是过度设计

D4: 模块结构 — 职责分离

决定： 按职责划分为以下模块：

src/llama_agent_skills/
├── __init__.py          # 包入口 + main()
├── skill.py             # Skill 数据模型 + SKILL.md 解析器
├── registry.py          # SkillRegistry（扫描、注册、查询）
├── agent.py             # Agent 构建与运行（封装 AgentWorkflow）
└── config.py            # 配置管理（环境变量、默认值）

理由：

• skill.py 专注数据解析，与 LlamaIndex 无关，可独立测试
• registry.py 管理 SKILL 生命周期，依赖 skill.py 但不依赖 agent.py
• agent.py 是唯一依赖 LlamaIndex 的模块，负责将 registry 中的 SKILL 组装为 Agent
• config.py 集中管理配置，避免硬编码散落

D5: SKILL 上下文组装策略

决定： 在 Agent 启动时，将所有已注册 SKILL 的正文按固定格式拼接到 system prompt：

{base_system_prompt}

---

## Active Skills

### Skill: {skill.name}
{skill.description}

{skill.body}

---

### Skill: {skill2.name}
...

理由：

• 结构化的分隔让 LLM 清楚区分不同 SKILL 的指令
• 每个 SKILL 带有名称和描述作为标题，便于 LLM 理解上下文切换
• 用 --- 分隔避免 SKILL 间指令混淆

Risks / Trade-offs

• [System prompt 长度爆炸] → 当加载多个大型 SKILL 时，system prompt 可能超出 LLM context window。缓解： 限制同时加载的 SKILL 数量，后续可引入选择性加载或摘要机制。

• [SKILL 间指令冲突] → 多个 SKILL 可能包含矛盾指令。缓解： 第一版不解决，通过文档约定 SKILL 应自包含；后续可增加冲突检测。

• [LlamaIndex 版本锁定] → 依赖 llama-index-core 的特定 API（如 AgentWorkflow），升级可能 break。缓解： 通过 agent.py 隔离 LlamaIndex 依赖，仅在该模块中引用 LlamaIndex API。

• [无 Shell 限制降低灵活性] → 部分 SKILL 可能期望执行 CLI 命令（如 openspec CLI）。缓解： 明确标记为 Non-Goal，后续可通过安全沙箱或 API wrapper 支持。

• [SKILL.md 格式无 schema 校验] → frontmatter 字段错误不会被提前发现。缓解： 在 skill.py 中做基本校验（必填字段检查），后续可引入 JSON Schema 或 Pydantic 校验。