Interactive Skills Platform Mvp

设计并落地 Skills Web 平台 MVP，让非技术用户无需 CLI 即可使用 SKILL.md 能力。 用于“skills 平台”“skill 网页化”“interactive skills platform”“上传 SKILL.md 生成 UI” “对话式执行 skill”等需求，输出可执行的架构方案、A...

Security Scan

The skill is a design/instruction-only template for building a web-based Skills MVP and is internally consistent with its stated purpose; it contains no code, no install steps, and requests no unrelated credentials, but it explicitly defers security/auth concerns which you should not ignore in real deployments.

Purpose & Capability

Name/description match the content: the SKILL.md is a product/architecture & implementation plan for a web Skills MVP (upload SKILL.md -> UI, dialogue flow, execution). All instructions and examples relate to that goal and do not request unrelated system access or credentials.

Instruction Scope

Instructions remain scoped to design and implementation guidance (architecture, API, workflows, example prompts). They reference using Claude API / Agent SDK and a file-backed skills store, which is consistent with the design purpose. However, the doc explicitly marks security sandboxing and authentication as 'Non-Goals' for MVP — this is a deliberate scope choice that increases operational risk if adopted without later remediation.

Install Mechanism

No install spec, no code files to write or execute. This is instruction-only so there is no install-time risk from downloads or arbitrary binaries.

Credentials

The skill declares no required env vars or credentials, which is reasonable for a design/template skill. That said, the runtime architecture it describes depends on external LLM APIs (Claude) and an Agent SDK — any real implementation will require API keys and network access. The SKILL.md does not declare or justify required credentials because it is a design doc, so you should expect to manage those secrets separately.

Persistence & Privilege

Skill is not always-enabled, has no install, does not request system-wide changes or modify other skills. It does not ask for persistent privileges or to modify agent configs.

Assessment

This skill is a planning/design template and appears coherent with its stated purpose. It contains no executable code and requests no credentials, but it intentionally excludes security sandboxing and authentication from the MVP scope — do not deploy the suggested architecture in production without adding sandbox isolation, proper authentication/authorization, API key management, and safety checks. Also plan for how Claude/Agent SDK credentials and file storage access will be provisioned and restricted (don’t hard-code keys or expose uploaded SKILL.md content to untrusted networks). If you want a deeper security review later, provide the implementation code or CI/deployment scripts so they can be audited for secret handling, network endpoints, and third-party downloads.

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 结构：

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 名称等）

文件存储结构：

skills/
├── felo-search/
│   ├── SKILL.md
│   └── metadata.json
└── felo-slides/
    ├── SKILL.md
    └── metadata.json

metadata.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 示例：

分析以下 SKILL.md，提取：
1. Skill 的功能描述（一句话）
2. 需要的输入参数（JSON 格式）
3. 需要的 UI 类型（chat/progress/link）
4. 预期输出类型（text/file/url）

SKILL.md:
{skill_content}

返回 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）：

AI: 这个 skill 可以帮你进行实时网络搜索，你想搜索什么？
User: 东京今天天气
AI: 好的，正在搜索"东京今天天气"...
[调用 skill 执行]
AI: [展示搜索结果]

对话流程示例（felo-slides）：

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 预览

前端组件：

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 执行：

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
• felo-skills Repository
• FastAPI Documentation
• React Documentation