back
loading skill details...
设计并落地 Skills Web 平台 MVP，让非技术用户无需 CLI 即可使用 SKILL.md 能力。 用于“skills 平台”“skill 网页化”“interactive skills platform”“上传 SKILL.md 生成 UI” “对话式执行 skill”等需求，输出可执行的架构方案、A...
---
name: interactive-skills-platform-mvp
description: >
设计并落地 Skills Web 平台 MVP，让非技术用户无需 CLI 即可使用 SKILL.md 能力。
用于“skills 平台”“skill 网页化”“interactive skills platform”“上传 SKILL.md 生成 UI”
“对话式执行 skill”等需求，输出可执行的架构方案、API 设计、分阶段清单、验收与风险计划。
model: opus
---
# Design: Interactive Skills Platform (MVP)
## 何时使用
当用户出现以下诉求时启用本 skill：
- “把 skill 做成网页给非技术用户用”
- “做一个 skills 平台 / interactive skills platform”
- “上传 SKILL.md 并自动生成交互 UI”
- “要对话式引导，而不是表单式参数输入”
## 目标产出
在一次会话内，默认交付以下内容（可按用户要求裁剪）：
1. 明确的 Problem/Goal/Non-Goal 定义
2. MVP 架构方案（前端、后端、存储、执行链路）
3. API 草案（上传、分析、对话、执行、状态查询）
4. 分阶段实施清单（按周）
5. 验证方案（至少用 2 个真实 skills）
6. 风险清单与后续迭代边界
## 执行工作流（必须按顺序）
### Phase 1: 问题对齐（最少提问）
- 先复述用户目标与边界，确认是否只做 MVP。
- 如果信息缺失，只问 1-3 个关键问题（例如部署环境、目标用户、首批 skills）。
- 明确是否已有代码仓库；若无，则按“新项目”输出。
### Phase 2: 方案设计（先给推荐）
- 先给一个推荐方案，再给备选方案，不做“选项轰炸”。
- 推荐方案必须覆盖：
- Monorepo 结构
- 前后端技术栈
- skills 存储与 metadata 结构
- Claude API 分析链路
- Agent SDK 执行链路
- 动态 UI 策略（text/progress/url）
### Phase 3: 交付可执行计划
- 输出分阶段任务，要求每项任务可直接实现和验收。
- 必须包含：
- 完成定义（Definition of Done）
- 基本测试用例
- 错误处理与回退策略
### Phase 4: MVP 现实性审查
- 强制检查是否过度设计（YAGNI）。
- 明确“本期不做什么”，避免范围蔓延。
- 标注 blocker（必须解决）与 nice-to-have（可后移）。
## 输出格式要求
- 默认中文输出，结构尽量固定：背景 -> 问题 -> 方案 -> 清单 -> 风险。
- 对架构和流程，优先给可落地清单而非抽象原则。
- 若用户要“直接开工”，把清单细化成可以逐步实现的工程任务。
- 若用户要“先评审”，给出关键 trade-off 与推荐结论。
## 质量标准
- 方案必须能支撑以下最小闭环：
1) 上传 SKILL.md
2) AI 分析出参数和 UI 配置
3) 对话收集参数
4) 执行 skill
5) 渲染结果（文本/进度/链接）
- 至少包含一个短任务样例（如 felo-search）和一个长任务样例（如 felo-slides）。
- 明确列出安全、认证、市场化等延后议题，避免假性完成。
## 参考设计稿（可直接复用）
> Status: Draft
> Created: 2026-03-06
> Repo: skills-ai-page (Monorepo)
## Background
Skills 创作者创作了有用的 skills（Claude Code/OpenClaw），但这些 skills 只能在命令行工具中运行，只有技术用户能用。创作者希望让更多非技术用户也能使用自己的 skills，从而扩大 skills 的影响力和价值。
## Problem Statement
**WHO**: Skills 创作者
**SITUATION**:
- 创作了有用的 skills（可能包含 Python 脚本、CLI 调用等）
- 想让更多人使用自己的 skills
- 但 skills 只能在 Claude Code/OpenClaw 中运行，只有技术用户能用
**PROBLEM**:
Skills 的传播和使用受限于技术门槛 - 潜在用户装不好 Claude Code/OpenClaw，创作者的作品无法触达非技术用户
**IMPACT**:
- 创作者的作品价值无法最大化
- 好的 skills 埋没在技术圈子里
- 无法形成 skills 创作者生态
## Related Features
目前没有 `.features/` 目录，这是新项目。
## Goals
1. **降低 skills 使用门槛** - 非技术用户无需安装 Claude Code，通过 Web 界面即可使用 skills
2. **智能交互体验** - 对话式引导 + 动态 UI，不只是填表单
3. **验证核心价值** - 用真实 skills（felo-skills）验证方案可行性
## Non-Goals
- 不做安全沙箱隔离（MVP 阶段不考虑，后面迭代）
- 不做用户认证和权限管理（MVP 阶段不考虑）
- 不做 skills 市场功能（发布、评分、付费等）
- 不做复杂的数据可视化（图表、地图等，MVP 只支持基础 UI）
## Jobs to be Done
**Functional Job**:
- Skills 创作者：让我的 skills 能被更多人使用
- 普通用户：不需要懂技术就能用 skills 完成任务
**Social Job**:
- 创作者：展示自己的作品，获得认可
- 用户：使用先进的 AI 工具，提升效率
**Emotional Job**:
- 创作者：成就感（作品被使用）
- 用户：轻松感（不需要学习复杂工具）
## Solution
### Overview
创建一个 Web 平台，用户上传 Claude Code 标准的 `SKILL.md` 文件，平台使用 Claude API 分析 skill 并生成交互界面，通过 Claude Agent SDK 执行 skills。
**核心特性：**
1. **对话式交互（A）** - 用户不填表单，而是跟 AI 对话，AI 引导用户提供必要信息
2. **动态 UI（B）** - 根据 skill 特性生成不同的交互界面（进度条、链接、预览等）
### Architecture
**Monorepo 结构：**
```text
skills-ai-page/
├── frontend/ # React + TypeScript
│ ├── src/
│ │ ├── components/
│ │ │ ├── Chat/ # 对话界面
│ │ │ ├── SkillUpload/ # 上传 skills
│ │ │ ├── DynamicUI/ # 动态 UI 组件
│ │ │ │ ├── ProgressBar.tsx
│ │ │ │ ├── LinkOutput.tsx
│ │ │ │ └── TextOutput.tsx
│ │ │ └── SkillList/ # Skills 列表
│ │ ├── pages/
│ │ ├── hooks/
│ │ └── store/ # Zustand 状态管理
│ └── package.json
├── backend/ # Python + FastAPI
│ ├── app/
│ │ ├── api/
│ │ │ ├── skills.py # Skills CRUD
│ │ │ ├── chat.py # 对话接口
│ │ │ └── execute.py # 执行 skills
│ │ ├── services/
│ │ │ ├── skill_analyzer.py # Claude 分析 SKILL.md
│ │ │ ├── agent_executor.py # Claude Agent SDK 执行
│ │ │ └── ui_generator.py # 生成 UI 配置
│ │ └── storage/
│ │ └── file_storage.py # 文件系统存储
│ ├── skills/ # Skills 存储目录
│ │ ├── felo-search/
│ │ │ ├── SKILL.md
│ │ │ └── metadata.json
│ │ └── felo-slides/
│ │ ├── SKILL.md
│ │ └── metadata.json
│ └── requirements.txt
└── README.md
```
### Detailed Design
#### 1. Skills 上传与存储
**用户上传 SKILL.md：**
- 前端：文件上传组件
- 后端：接收文件，保存到 `skills/{skill-name}/SKILL.md`
- 生成 `metadata.json`（创建时间、skill 名称等）
**文件存储结构：**
```text
skills/
├── felo-search/
│ ├── SKILL.md
│ └── metadata.json
└── felo-slides/
├── SKILL.md
└── metadata.json
```
**metadata.json 格式：**
```json
{
"name": "felo-search",
"description": "Real-time web search",
"created_at": "2026-03-06T10:00:00Z",
"author": "anonymous",
"ui_config": {
"type": "chat",
"supports_progress": false,
"output_types": ["text", "markdown"]
}
}
```
#### 2. AI 分析 SKILL.md
**调用 Claude API 分析：**
- 输入：SKILL.md 内容
- 输出：
- Skill 功能描述
- 需要的参数（名称、类型、描述）
- 需要的 UI 类型（chat、progress、link 等）
- 预期输出类型（text、file、url 等）
**Prompt 示例：**
```text
分析以下 SKILL.md，提取：
1. Skill 的功能描述（一句话）
2. 需要的输入参数（JSON 格式）
3. 需要的 UI 类型（chat/progress/link）
4. 预期输出类型（text/file/url）
SKILL.md:
{skill_content}
返回 JSON 格式。
```
**返回示例：**
```json
{
"description": "Real-time web search with AI-generated answers",
"parameters": [
{
"name": "query",
"type": "string",
"description": "Search query",
"required": true
}
],
"ui_type": "chat",
"supports_progress": false,
"output_types": ["text", "markdown"]
}
```
#### 3. 对话式交互
**用户点击"使用这个 skill"：**
1. 进入对话界面（类似 ChatGPT）
2. AI 发送欢迎消息：「这个 skill 可以帮你 {description}，你想做什么？」
3. 用户输入需求
4. AI 引导用户提供必要参数（对话式）
5. 参数收集完成后，调用后端执行 skill
**对话流程示例（felo-search）：**
```text
AI: 这个 skill 可以帮你进行实时网络搜索，你想搜索什么？
User: 东京今天天气
AI: 好的，正在搜索"东京今天天气"...
[调用 skill 执行]
AI: [展示搜索结果]
```
**对话流程示例（felo-slides）：**
```text
AI: 这个 skill 可以帮你生成 PPT，你想生成什么主题的 PPT？
User: React 入门教程，5 页
AI: 好的，正在生成"React 入门教程"PPT，大约需要 5-10 分钟...
[显示进度条]
AI: PPT 生成完成！[点击查看](https://...)
```
#### 4. 动态 UI 渲染
**根据 skill 的 ui_config 渲染不同的 UI：**
**A) 基础对话（默认）：**
- 文本输入/输出
- Markdown 渲染
**B) 进度展示：**
- 进度条组件
- 状态文本（进行中/完成/失败）
- 用于长时间运行的 skills（如 felo-slides）
**C) 链接输出：**
- 可点击的链接
- 可选：iframe 预览
**前端组件：**
```tsx
function DynamicUI({ uiConfig, data }) {
if (uiConfig.supports_progress && data.status === "running") {
return <ProgressBar progress={data.progress} />;
}
if (uiConfig.output_types.includes("url")) {
return <LinkOutput url={data.url} />;
}
return <TextOutput content={data.content} />;
}
```
#### 5. 执行 Skills
**后端使用 Claude Agent SDK 执行：**
```python
from claude_agent_sdk import Agent
async def execute_skill(skill_name: str, parameters: dict):
# 读取 SKILL.md
skill_path = f"skills/{skill_name}/SKILL.md"
with open(skill_path, "r", encoding="utf-8") as f:
skill_content = f.read()
# 创建 Agent
agent = Agent(skill_content=skill_content)
# 执行
result = await agent.execute(parameters)
return result
```
**执行流程：**
1. 前端发送执行请求（skill_name + parameters）
2. 后端创建 Agent，加载 SKILL.md
3. Agent SDK 执行 skill（调用 Bash 工具、Claude API 等）
4. 返回结果给前端
5. 前端根据 ui_config 渲染结果
#### 6. MVP 支持的 UI 类型
| UI 类型 | 用途 | 示例 Skill |
|---------|------|-----------|
| 对话式交互 | 文本输入/输出 | felo-search |
| 进度展示 | 长时间任务状态 | felo-slides |
| 链接输出 | URL 结果 | felo-slides |
**不支持（后面迭代）：**
- 文件上传/下载
- 数据可视化（图表）
- 画布/编辑器
- 地图/视频
### Why This Approach
**为什么选择对话式交互 + 动态 UI？**
- **差异化价值** - 其他平台都是填表单，我们是对话式，更自然
- **降低门槛** - 用户不需要理解参数，AI 引导即可
- **更好的体验** - 动态 UI 让 skills 看起来像真正的产品
**为什么选择 Python + FastAPI？**
- Claude Agent SDK 有 Python 版本，集成方便
- FastAPI 现代、快速，适合 API 开发
- Python 生态丰富，适合 AI 相关开发
**为什么选择文件存储而不是数据库？**
- MVP 阶段快速验证，不需要配置数据库
- 文件存储符合 skills 的文件结构（SKILL.md）
- 版本控制友好（可以用 git）
- 后面可以轻松迁移到数据库
**为什么选择 Monorepo？**
- MVP 阶段代码量不大，放一起方便管理
- 前后端可以共享类型定义
- 部署简单
## Alternatives Considered
### Option A: 只生成表单，不做对话式交互
- **优点**: 实现简单，工作量小
- **缺点**: 用户体验差，没有差异化价值
- **拒绝理由**: 不够 cool，无法吸引用户
### Option B: 支持所有类型的动态 UI（图表、画布、编辑器等）
- **优点**: 功能强大，用户体验好
- **缺点**: 工作量大，MVP 阶段不现实
- **拒绝理由**: 过度设计，先验证核心价值
### Option C: 后端用 Node.js
- **优点**: 前后端语言统一，性能好
- **缺点**: Claude Agent SDK 的 Node.js 支持不如 Python
- **拒绝理由**: Python 更适合 AI 相关开发
### Option D: 使用数据库存储
- **优点**: 查询效率高，扩展性好
- **缺点**: 需要配置数据库，增加复杂度
- **拒绝理由**: MVP 阶段不需要，文件存储足够
## Implementation Checklist
### Phase 1: 基础架构（Week 1）
- [ ] 创建 Monorepo 项目结构
- [ ] 前端：React + TypeScript + Tailwind CSS 脚手架
- [ ] 后端：Python + FastAPI 脚手架
- [ ] 文件存储：实现 skills 的 CRUD 操作
- [ ] API 设计：定义前后端接口
### Phase 2: Skills 上传与分析（Week 1-2）
- [ ] 前端：Skills 上传组件
- [ ] 后端：接收并保存 SKILL.md
- [ ] 集成 Claude API：分析 SKILL.md
- [ ] 生成 ui_config（UI 类型、参数定义）
- [ ] 前端：Skills 列表展示
### Phase 3: 对话式交互（Week 2-3）
- [ ] 前端：对话界面组件（类似 ChatGPT）
- [ ] 后端：对话接口（接收用户消息，返回 AI 回复）
- [ ] 集成 Claude API：引导用户提供参数
- [ ] 参数收集逻辑（对话式）
- [ ] 前端：消息渲染（Markdown 支持）
### Phase 4: 动态 UI（Week 3）
- [ ] 前端：进度条组件
- [ ] 前端：链接输出组件
- [ ] 前端：文本输出组件（Markdown）
- [ ] 前端：根据 ui_config 动态渲染
- [ ] 后端：返回 UI 配置给前端
### Phase 5: Skills 执行（Week 3-4）
- [ ] 集成 Claude Agent SDK（Python）
- [ ] 后端：执行 skills 接口
- [ ] 后端：处理长时间任务（进度更新）
- [ ] 前端：轮询任务状态（felo-slides）
- [ ] 错误处理和重试逻辑
### Phase 6: 验证与测试（Week 4）
- [ ] 导入 felo-skills 仓库的两个 skills
- [ ] 测试 felo-search（对话式搜索）
- [ ] 测试 felo-slides（进度展示 + 链接输出）
- [ ] 修复 bug 和优化体验
- [ ] 部署到测试环境
### Phase 7: 部署（Week 4）
- [ ] 前端部署到 Vercel/Netlify
- [ ] 后端部署到云服务器
- [ ] 配置域名和 HTTPS
- [ ] 监控和日志
## Open Questions
### 1. 安全性问题（后面迭代）
- **问题**: Skills 可以执行任意 CLI 命令，如何防止恶意代码？
- **可能方案**:
- 容器隔离（Docker/K8s）
- 沙箱执行（Firecracker、gVisor）
- 白名单 CLI（只允许安全命令）
- 人工审核 + 容器隔离
- **决策时机**: V2 迭代时讨论
### 2. 数据库迁移（后面迭代）
- **问题**: 文件存储扩展性差，何时迁移到数据库？
- **可能方案**: PostgreSQL + SQLAlchemy
- **决策时机**: 用户数 > 100 或 skills 数 > 50 时
### 3. 用户认证（后面迭代）
- **问题**: 如何管理用户和权限？
- **可能方案**:
- OAuth（GitHub、Google）
- 自建用户系统
- **决策时机**: V2 迭代时讨论
### 4. Skills 市场（后面迭代）
- **问题**: 如何让创作者发布、分享、甚至售卖 skills？
- **可能方案**:
- 公开/私有 skills
- 评分和评论
- 付费 skills（Stripe 集成）
- **决策时机**: V3 迭代时讨论
### 5. 更多 UI 类型（后面迭代）
- **问题**: 何时支持图表、画布、编辑器等复杂 UI？
- **可能方案**:
- 图表：ECharts/Recharts
- 画布：Fabric.js/Konva
- 编辑器：Monaco Editor/CodeMirror
- **决策时机**: 根据用户反馈决定优先级
## References
- [Claude Agent SDK Documentation](https://github.com/anthropics/anthropic-sdk-python)
- [felo-skills Repository](https://github.com/Felo-Inc/felo-skills)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [React Documentation](https://react.dev/)
don't have the plugin yet? install it then click "run inline in claude" again.