skillfmt 0.1.3

AI Skill 格式转换与管理工具 — 写一次定义，导出到所有主流 AI 平台

Skills Manager v0.1.3

写一次 AI Skill 定义，一键导出为 OpenAI / Claude / Gemini / MCP 等主流平台格式。

快速安装

pip install skillfmt

CLI 命令 skillfmt 安装后即可使用。桌面应用请从 Releases 下载。

快速开始

1. 创建一个 Skill

创建目录 my-skill/，在其中创建 SKILL.md：

---
name: hello
version: "1.0.0"
description: 一个简单的问候工具
summary: 向用户打招呼，支持中英文。
skill_type: component
intent: 用于测试和演示的简单问候工具
tags: [demo, greeting]
category: misc
---

## 功能

向用户打招呼。

## 参数

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| name | string | 是 | 用户名称 |
| language | string | 否 | 语言：zh / en，默认 zh |

## 示例

```json
{"name": "世界", "language": "zh"}

{"greeting": "你好，世界！"}

适用场景

• 测试 Skill 系统
• 演示基本功能

不适用

• 生产环境使用

### 2. 安装并导出

```bash
# 安装 Skill
skillfmt install ./my-skill

# 导出为 OpenAI 格式
skillfmt export hello --format openai

# 导出为 Claude 格式
skillfmt export hello --format claude

# 导出为 MCP Server
skillfmt export hello --format mcp --output hello_mcp.py

3. 桌面应用

从 Releases 下载安装包，或从源码运行：

python -m desktop

4. 检查更新

skillfmt check-update

SKILL.md 格式规范

Frontmatter（必填）

---
name: skill-name          # 必填：唯一标识，小写 + 连字符
version: "1.0.0"          # 必填：语义化版本
description: 一句话描述    # 必填：简短描述（< 200 字）
summary: |                # 必填：2-3 句话摘要
  详细描述这个 Skill 的功能。
  支持多行文本。
---

Frontmatter（可选）

---
# 语义类型
skill_type: component     # component | interactive | workflow
intent: 详细意图说明       # 这个 Skill 要解决什么问题

# 分类
tags: [tag1, tag2]        # 自由标签
category: language        # 一级分类标识

# 执行配置
executor:
  type: python            # python | node | shell | http
  entry: handler.py       # 入口文件
  function: translate     # 入口函数名

# 安全声明
security:
  needs_network: true
  needs_api_key: true

# 元信息
author: someone
license: MIT
---

Markdown Body

## 功能

详细描述 Skill 的功能。

## 参数

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| param1 | string | ✅ | 参数说明 |
| param2 | integer | ❌ | 可选参数 |

## 返回

| 字段 | 类型 | 说明 |
|------|------|------|
| result | string | 返回结果 |

## 示例

输入：
```json
{"param1": "value"}

输出：

{"result": "processed"}

适用场景

• 场景 1
• 场景 2

不适用

• 不适用场景 1

## 支持的导出格式

| 格式 | 说明 | 文件扩展名 |
|------|------|-----------|
| openai | OpenAI Function Calling | .json |
| claude | Claude Tool Use | .json |
| gemini | Gemini Function Declaration | .json |
| mcp | MCP Server（可运行） | .py |
| schema | JSON Schema | .json |

## 项目结构

skills-manager/ ├── README.md # 本文件 ├── LICENSE # MIT 许可证 ├── pyproject.toml # 项目配置 & PyPI 元数据 ├── src/skills_manager/ # 核心引擎 │ ├── init.py │ ├── ir.py # 中间表示（IR） │ ├── parser.py # SKILL.md 解析器 │ ├── store/ # 本地存储管理（缓存+降级恢复） │ │ ├── init.py # Store 门面类（组合各 mixin） │ │ ├── core.py # 索引读写、基础查询、搜索 │ │ ├── installer.py # 安装/卸载/升级/回滚 │ │ ├── scanner.py # 目录扫描与自动发现 │ │ ├── agent_sync.py # Agent 目录同步 │ │ ├── category.py # 自动分类 │ │ ├── translation.py # 翻译管理 │ │ ├── profile.py # Profile 管理 │ │ └── history.py # 使用/导出历史、收藏 │ ├── validator.py # 格式验证器 │ ├── packager.py # 打包器 │ ├── agent_config.py # Agent 配置生成 │ ├── security.py # 安全工具（路径穿越防护） │ ├── logging.py # 结构化日志系统 │ ├── updater.py # 自动更新检查 │ ├── cli.py # CLI 入口（Typer） │ ├── claude_code_checker.py # Claude Code 兼容性检查 │ └── adapters/ # 格式适配器 │ ├── base.py # 适配器基类 │ ├── openai.py # OpenAI Function Calling │ ├── claude.py # Claude Tool Use │ ├── gemini.py # Gemini Function Declaration │ ├── mcp.py # MCP Python Server │ └── json_schema.py # JSON Schema ├── desktop/ # 桌面客户端（Flet 0.84） │ ├── main.py # 入口 │ ├── app.py # 主控类（状态/导航/更新检查） │ ├── components.py # 可复用组件（卡片/列表/字体） │ ├── dialogs.py # 对话框 │ └── pages/ # 页面 │ ├── browse.py # 浏览页（搜索/筛选） │ ├── detail.py # 详情页（参数表/导出预览） │ ├── export.py # 批量导出 │ ├── editor.py # 编辑器（实时预览） │ ├── import_page.py # 批量导入 │ ├── profiles.py # Profile 管理 │ ├── recommend.py # 推荐 │ └── settings.py # 设置 ├── installer/ # 安装包 │ └── setup.nsi # Windows NSIS 安装脚本 ├── pyinstaller/ # 打包入口 │ ├── cli_launcher.py │ └── desktop_launcher.py ├── .github/workflows/ # CI/CD │ └── release.yml # 三平台构建 + PyPI 发布 ├── examples/ # 示例 Skills (6 个) ├── tests/ # 测试 (271 passed) └── docs/ # 文档

## 开发指南

### 运行测试

```bash
# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_parser.py -v

# 查看覆盖率
pytest tests/ --cov=skills_manager --cov-report=term-missing

代码质量

# 格式化
ruff format .

# 检查
ruff check .

# 类型检查
mypy src/

添加新适配器

1. 在 src/skills_manager/adapters/ 创建新文件
2. 继承 BaseAdapter 类
3. 实现 name、file_extension、export 方法
4. 在 __init__.py 注册适配器
5. 添加测试

添加新验证规则

1. 在 src/skills_manager/validator.py 添加规则
2. 返回 ValidationResult（errors 或 warnings）
3. 添加测试用例

文档

• 用户指南 — 详细使用说明

许可

MIT