Skill: wangzhiming1999/interactive-skills-platform-mvp (version 1.0.0)

--- 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/)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)