\r \r

Design: Interactive Skills Platform (MVP)\r

\r

何时使用\r

\r 当用户出现以下诉求时启用本 skill：\r

• “把 skill 做成网页给非技术用户用”\r
• “做一个 skills 平台 / interactive skills platform”\r
• “上传 SKILL.md 并自动生成交互 UI”\r
• “要对话式引导，而不是表单式参数输入”\r \r

目标产出\r

\r 在一次会话内，默认交付以下内容（可按用户要求裁剪）：\r

1. 明确的 Problem/Goal/Non-Goal 定义\r
2. MVP 架构方案（前端、后端、存储、执行链路）\r
3. API 草案（上传、分析、对话、执行、状态查询）\r
4. 分阶段实施清单（按周）\r
5. 验证方案（至少用 2 个真实 skills）\r
6. 风险清单与后续迭代边界\r \r

执行工作流（必须按顺序）\r

\r

Phase 1: 问题对齐（最少提问）\r

\r

• 先复述用户目标与边界，确认是否只做 MVP。\r
• 如果信息缺失，只问 1-3 个关键问题（例如部署环境、目标用户、首批 skills）。\r
• 明确是否已有代码仓库；若无，则按“新项目”输出。\r \r

Phase 2: 方案设计（先给推荐）\r

\r

• 先给一个推荐方案，再给备选方案，不做“选项轰炸”。\r
• 推荐方案必须覆盖：\r
  • Monorepo 结构\r
  • 前后端技术栈\r
  • skills 存储与 metadata 结构\r
  • Claude API 分析链路\r
  • Agent SDK 执行链路\r
  • 动态 UI 策略（text/progress/url）\r \r

Phase 3: 交付可执行计划\r

\r

• 输出分阶段任务，要求每项任务可直接实现和验收。\r
• 必须包含：\r
  • 完成定义（Definition of Done）\r
  • 基本测试用例\r
  • 错误处理与回退策略\r \r

Phase 4: MVP 现实性审查\r

\r

• 强制检查是否过度设计（YAGNI）。\r
• 明确“本期不做什么”，避免范围蔓延。\r
• 标注 blocker（必须解决）与 nice-to-have（可后移）。\r \r

输出格式要求\r

\r

• 默认中文输出，结构尽量固定：背景 -> 问题 -> 方案 -> 清单 -> 风险。\r
• 对架构和流程，优先给可落地清单而非抽象原则。\r
• 若用户要“直接开工”，把清单细化成可以逐步实现的工程任务。\r
• 若用户要“先评审”，给出关键 trade-off 与推荐结论。\r \r

质量标准\r

\r

• 方案必须能支撑以下最小闭环：\r
  1. 上传 SKILL.md\r
  2. AI 分析出参数和 UI 配置\r
  3. 对话收集参数\r
  4. 执行 skill\r
  5. 渲染结果（文本/进度/链接）\r
• 至少包含一个短任务样例（如 felo-search）和一个长任务样例（如 felo-slides）。\r
• 明确列出安全、认证、市场化等延后议题，避免假性完成。\r \r

参考设计稿（可直接复用）\r

\r

Status: Draft\r Created: 2026-03-06\r Repo: skills-ai-page (Monorepo)\r \r

Background\r

\r Skills 创作者创作了有用的 skills（Claude Code/OpenClaw），但这些 skills 只能在命令行工具中运行，只有技术用户能用。创作者希望让更多非技术用户也能使用自己的 skills，从而扩大 skills 的影响力和价值。\r \r

Problem Statement\r

\r WHO: Skills 创作者\r \r SITUATION:\r

• 创作了有用的 skills（可能包含 Python 脚本、CLI 调用等）\r
• 想让更多人使用自己的 skills\r
• 但 skills 只能在 Claude Code/OpenClaw 中运行，只有技术用户能用\r \r PROBLEM:\r Skills 的传播和使用受限于技术门槛 - 潜在用户装不好 Claude Code/OpenClaw，创作者的作品无法触达非技术用户\r \r IMPACT:\r
• 创作者的作品价值无法最大化\r
• 好的 skills 埋没在技术圈子里\r
• 无法形成 skills 创作者生态\r \r

Related Features\r

\r 目前没有 .features/ 目录，这是新项目。\r \r

Goals\r

\r

1. 降低 skills 使用门槛 - 非技术用户无需安装 Claude Code，通过 Web 界面即可使用 skills\r
2. 智能交互体验 - 对话式引导 + 动态 UI，不只是填表单\r
3. 验证核心价值 - 用真实 skills（felo-skills）验证方案可行性\r \r

Non-Goals\r

\r

• 不做安全沙箱隔离（MVP 阶段不考虑，后面迭代）\r
• 不做用户认证和权限管理（MVP 阶段不考虑）\r
• 不做 skills 市场功能（发布、评分、付费等）\r
• 不做复杂的数据可视化（图表、地图等，MVP 只支持基础 UI）\r \r

Jobs to be Done\r

\r Functional Job:\r

• Skills 创作者：让我的 skills 能被更多人使用\r
• 普通用户：不需要懂技术就能用 skills 完成任务\r \r Social Job:\r
• 创作者：展示自己的作品，获得认可\r
• 用户：使用先进的 AI 工具，提升效率\r \r Emotional Job:\r
• 创作者：成就感（作品被使用）\r
• 用户：轻松感（不需要学习复杂工具）\r \r

Solution\r

\r

Overview\r

\r 创建一个 Web 平台，用户上传 Claude Code 标准的 SKILL.md 文件，平台使用 Claude API 分析 skill 并生成交互界面，通过 Claude Agent SDK 执行 skills。\r \r 核心特性：\r

1. 对话式交互（A） - 用户不填表单，而是跟 AI 对话，AI 引导用户提供必要信息\r
2. 动态 UI（B） - 根据 skill 特性生成不同的交互界面（进度条、链接、预览等）\r \r

Architecture\r

\r Monorepo 结构：\r \r

skills-ai-page/\r
├── frontend/          # React + TypeScript\r
│   ├── src/\r
│   │   ├── components/\r
│   │   │   ├── Chat/           # 对话界面\r
│   │   │   ├── SkillUpload/    # 上传 skills\r
│   │   │   ├── DynamicUI/      # 动态 UI 组件\r
│   │   │   │   ├── ProgressBar.tsx\r
│   │   │   │   ├── LinkOutput.tsx\r
│   │   │   │   └── TextOutput.tsx\r
│   │   │   └── SkillList/      # Skills 列表\r
│   │   ├── pages/\r
│   │   ├── hooks/\r
│   │   └── store/              # Zustand 状态管理\r
│   └── package.json\r
├── backend/           # Python + FastAPI\r
│   ├── app/\r
│   │   ├── api/\r
│   │   │   ├── skills.py       # Skills CRUD\r
│   │   │   ├── chat.py         # 对话接口\r
│   │   │   └── execute.py      # 执行 skills\r
│   │   ├── services/\r
│   │   │   ├── skill_analyzer.py    # Claude 分析 SKILL.md\r
│   │   │   ├── agent_executor.py    # Claude Agent SDK 执行\r
│   │   │   └── ui_generator.py      # 生成 UI 配置\r
│   │   └── storage/\r
│   │       └── file_storage.py      # 文件系统存储\r
│   ├── skills/                      # Skills 存储目录\r
│   │   ├── felo-search/\r
│   │   │   ├── SKILL.md\r
│   │   │   └── metadata.json\r
│   │   └── felo-slides/\r
│   │       ├── SKILL.md\r
│   │       └── metadata.json\r
│   └── requirements.txt\r
└── README.md\r
```\r
\r
### Detailed Design\r
\r
#### 1. Skills 上传与存储\r
\r
**用户上传 SKILL.md：**\r
- 前端：文件上传组件\r
- 后端：接收文件，保存到 `skills/{skill-name}/SKILL.md`\r
- 生成 `metadata.json`（创建时间、skill 名称等）\r
\r
**文件存储结构：**\r
```text\r
skills/\r
├── felo-search/\r
│   ├── SKILL.md\r
│   └── metadata.json\r
└── felo-slides/\r
    ├── SKILL.md\r
    └── metadata.json\r
```\r
\r
**metadata.json 格式：**\r
```json\r
{\r
  "name": "felo-search",\r
  "description": "Real-time web search",\r
  "created_at": "2026-03-06T10:00:00Z",\r
  "author": "anonymous",\r
  "ui_config": {\r
    "type": "chat",\r
    "supports_progress": false,\r
    "output_types": ["text", "markdown"]\r
  }\r
}\r
```\r
\r
#### 2. AI 分析 SKILL.md\r
\r
**调用 Claude API 分析：**\r
- 输入：SKILL.md 内容\r
- 输出：\r
  - Skill 功能描述\r
  - 需要的参数（名称、类型、描述）\r
  - 需要的 UI 类型（chat、progress、link 等）\r
  - 预期输出类型（text、file、url 等）\r
\r
**Prompt 示例：**\r
```text\r
分析以下 SKILL.md，提取：\r
1. Skill 的功能描述（一句话）\r
2. 需要的输入参数（JSON 格式）\r
3. 需要的 UI 类型（chat/progress/link）\r
4. 预期输出类型（text/file/url）\r
\r
SKILL.md:\r
{skill_content}\r
\r
返回 JSON 格式。\r
```\r
\r
**返回示例：**\r
```json\r
{\r
  "description": "Real-time web search with AI-generated answers",\r
  "parameters": [\r
    {\r
      "name": "query",\r
      "type": "string",\r
      "description": "Search query",\r
      "required": true\r
    }\r
  ],\r
  "ui_type": "chat",\r
  "supports_progress": false,\r
  "output_types": ["text", "markdown"]\r
}\r
```\r
\r
#### 3. 对话式交互\r
\r
**用户点击"使用这个 skill"：**\r
1. 进入对话界面（类似 ChatGPT）\r
2. AI 发送欢迎消息：「这个 skill 可以帮你 {description}，你想做什么？」\r
3. 用户输入需求\r
4. AI 引导用户提供必要参数（对话式）\r
5. 参数收集完成后，调用后端执行 skill\r
\r
**对话流程示例（felo-search）：**\r
```text\r
AI: 这个 skill 可以帮你进行实时网络搜索，你想搜索什么？\r
User: 东京今天天气\r
AI: 好的，正在搜索"东京今天天气"...\r
[调用 skill 执行]\r
AI: [展示搜索结果]\r
```\r
\r
**对话流程示例（felo-slides）：**\r
```text\r
AI: 这个 skill 可以帮你生成 PPT，你想生成什么主题的 PPT？\r
User: React 入门教程，5 页\r
AI: 好的，正在生成"React 入门教程"PPT，大约需要 5-10 分钟...\r
[显示进度条]\r
AI: PPT 生成完成！[点击查看](https://...)\r
```\r
\r
#### 4. 动态 UI 渲染\r
\r
**根据 skill 的 ui_config 渲染不同的 UI：**\r
\r
**A) 基础对话（默认）：**\r
- 文本输入/输出\r
- Markdown 渲染\r
\r
**B) 进度展示：**\r
- 进度条组件\r
- 状态文本（进行中/完成/失败）\r
- 用于长时间运行的 skills（如 felo-slides）\r
\r
**C) 链接输出：**\r
- 可点击的链接\r
- 可选：iframe 预览\r
\r
**前端组件：**\r
```tsx\r
function DynamicUI({ uiConfig, data }) {\r
  if (uiConfig.supports_progress && data.status === "running") {\r
    return \x3CProgressBar progress={data.progress} />;\r
  }\r
\r
  if (uiConfig.output_types.includes("url")) {\r
    return \x3CLinkOutput url={data.url} />;\r
  }\r
\r
  return \x3CTextOutput content={data.content} />;\r
}\r
```\r
\r
#### 5. 执行 Skills\r
\r
**后端使用 Claude Agent SDK 执行：**\r
\r
```python\r
from claude_agent_sdk import Agent\r
\r
async def execute_skill(skill_name: str, parameters: dict):\r
    # 读取 SKILL.md\r
    skill_path = f"skills/{skill_name}/SKILL.md"\r
    with open(skill_path, "r", encoding="utf-8") as f:\r
        skill_content = f.read()\r
\r
    # 创建 Agent\r
    agent = Agent(skill_content=skill_content)\r
\r
    # 执行\r
    result = await agent.execute(parameters)\r
\r
    return result\r
```\r
\r
**执行流程：**\r
1. 前端发送执行请求（skill_name + parameters）\r
2. 后端创建 Agent，加载 SKILL.md\r
3. Agent SDK 执行 skill（调用 Bash 工具、Claude API 等）\r
4. 返回结果给前端\r
5. 前端根据 ui_config 渲染结果\r
\r
#### 6. MVP 支持的 UI 类型\r
\r
| UI 类型 | 用途 | 示例 Skill |\r
|---------|------|-----------|\r
| 对话式交互 | 文本输入/输出 | felo-search |\r
| 进度展示 | 长时间任务状态 | felo-slides |\r
| 链接输出 | URL 结果 | felo-slides |\r
\r
**不支持（后面迭代）：**\r
- 文件上传/下载\r
- 数据可视化（图表）\r
- 画布/编辑器\r
- 地图/视频\r
\r
### Why This Approach\r
\r
**为什么选择对话式交互 + 动态 UI？**\r
- **差异化价值** - 其他平台都是填表单，我们是对话式，更自然\r
- **降低门槛** - 用户不需要理解参数，AI 引导即可\r
- **更好的体验** - 动态 UI 让 skills 看起来像真正的产品\r
\r
**为什么选择 Python + FastAPI？**\r
- Claude Agent SDK 有 Python 版本，集成方便\r
- FastAPI 现代、快速，适合 API 开发\r
- Python 生态丰富，适合 AI 相关开发\r
\r
**为什么选择文件存储而不是数据库？**\r
- MVP 阶段快速验证，不需要配置数据库\r
- 文件存储符合 skills 的文件结构（SKILL.md）\r
- 版本控制友好（可以用 git）\r
- 后面可以轻松迁移到数据库\r
\r
**为什么选择 Monorepo？**\r
- MVP 阶段代码量不大，放一起方便管理\r
- 前后端可以共享类型定义\r
- 部署简单\r
\r
## Alternatives Considered\r
\r
### Option A: 只生成表单，不做对话式交互\r
- **优点**: 实现简单，工作量小\r
- **缺点**: 用户体验差，没有差异化价值\r
- **拒绝理由**: 不够 cool，无法吸引用户\r
\r
### Option B: 支持所有类型的动态 UI（图表、画布、编辑器等）\r
- **优点**: 功能强大，用户体验好\r
- **缺点**: 工作量大，MVP 阶段不现实\r
- **拒绝理由**: 过度设计，先验证核心价值\r
\r
### Option C: 后端用 Node.js\r
- **优点**: 前后端语言统一，性能好\r
- **缺点**: Claude Agent SDK 的 Node.js 支持不如 Python\r
- **拒绝理由**: Python 更适合 AI 相关开发\r
\r
### Option D: 使用数据库存储\r
- **优点**: 查询效率高，扩展性好\r
- **缺点**: 需要配置数据库，增加复杂度\r
- **拒绝理由**: MVP 阶段不需要，文件存储足够\r
\r
## Implementation Checklist\r
\r
### Phase 1: 基础架构（Week 1）\r
- [ ] 创建 Monorepo 项目结构\r
- [ ] 前端：React + TypeScript + Tailwind CSS 脚手架\r
- [ ] 后端：Python + FastAPI 脚手架\r
- [ ] 文件存储：实现 skills 的 CRUD 操作\r
- [ ] API 设计：定义前后端接口\r
\r
### Phase 2: Skills 上传与分析（Week 1-2）\r
- [ ] 前端：Skills 上传组件\r
- [ ] 后端：接收并保存 SKILL.md\r
- [ ] 集成 Claude API：分析 SKILL.md\r
- [ ] 生成 ui_config（UI 类型、参数定义）\r
- [ ] 前端：Skills 列表展示\r
\r
### Phase 3: 对话式交互（Week 2-3）\r
- [ ] 前端：对话界面组件（类似 ChatGPT）\r
- [ ] 后端：对话接口（接收用户消息，返回 AI 回复）\r
- [ ] 集成 Claude API：引导用户提供参数\r
- [ ] 参数收集逻辑（对话式）\r
- [ ] 前端：消息渲染（Markdown 支持）\r
\r
### Phase 4: 动态 UI（Week 3）\r
- [ ] 前端：进度条组件\r
- [ ] 前端：链接输出组件\r
- [ ] 前端：文本输出组件（Markdown）\r
- [ ] 前端：根据 ui_config 动态渲染\r
- [ ] 后端：返回 UI 配置给前端\r
\r
### Phase 5: Skills 执行（Week 3-4）\r
- [ ] 集成 Claude Agent SDK（Python）\r
- [ ] 后端：执行 skills 接口\r
- [ ] 后端：处理长时间任务（进度更新）\r
- [ ] 前端：轮询任务状态（felo-slides）\r
- [ ] 错误处理和重试逻辑\r
\r
### Phase 6: 验证与测试（Week 4）\r
- [ ] 导入 felo-skills 仓库的两个 skills\r
- [ ] 测试 felo-search（对话式搜索）\r
- [ ] 测试 felo-slides（进度展示 + 链接输出）\r
- [ ] 修复 bug 和优化体验\r
- [ ] 部署到测试环境\r
\r
### Phase 7: 部署（Week 4）\r
- [ ] 前端部署到 Vercel/Netlify\r
- [ ] 后端部署到云服务器\r
- [ ] 配置域名和 HTTPS\r
- [ ] 监控和日志\r
\r
## Open Questions\r
\r
### 1. 安全性问题（后面迭代）\r
- **问题**: Skills 可以执行任意 CLI 命令，如何防止恶意代码？\r
- **可能方案**:\r
  - 容器隔离（Docker/K8s）\r
  - 沙箱执行（Firecracker、gVisor）\r
  - 白名单 CLI（只允许安全命令）\r
  - 人工审核 + 容器隔离\r
- **决策时机**: V2 迭代时讨论\r
\r
### 2. 数据库迁移（后面迭代）\r
- **问题**: 文件存储扩展性差，何时迁移到数据库？\r
- **可能方案**: PostgreSQL + SQLAlchemy\r
- **决策时机**: 用户数 > 100 或 skills 数 > 50 时\r
\r
### 3. 用户认证（后面迭代）\r
- **问题**: 如何管理用户和权限？\r
- **可能方案**:\r
  - OAuth（GitHub、Google）\r
  - 自建用户系统\r
- **决策时机**: V2 迭代时讨论\r
\r
### 4. Skills 市场（后面迭代）\r
- **问题**: 如何让创作者发布、分享、甚至售卖 skills？\r
- **可能方案**:\r
  - 公开/私有 skills\r
  - 评分和评论\r
  - 付费 skills（Stripe 集成）\r
- **决策时机**: V3 迭代时讨论\r
\r
### 5. 更多 UI 类型（后面迭代）\r
- **问题**: 何时支持图表、画布、编辑器等复杂 UI？\r
- **可能方案**:\r
  - 图表：ECharts/Recharts\r
  - 画布：Fabric.js/Konva\r
  - 编辑器：Monaco Editor/CodeMirror\r
- **决策时机**: 根据用户反馈决定优先级\r
\r
## References\r
\r
- [Claude Agent SDK Documentation](https://github.com/anthropics/anthropic-sdk-python)\r
- [felo-skills Repository](https://github.com/Felo-Inc/felo-skills)\r
- [FastAPI Documentation](https://fastapi.tiangolo.com/)\r
- [React Documentation](https://react.dev/)\r