skillfmt 0.1.0__py3-none-any.whl

skillfmt-0.1.0.dist-info/METADATA

@@ -0,0 +1,407 @@
+Metadata-Version: 2.4
+Name: skillfmt
+Version: 0.1.0
+Summary: AI Skill 格式转换与管理工具 — 写一次定义，导出到所有主流 AI 平台
+Project-URL: Homepage, https://github.com/user/skills-manager
+Project-URL: Repository, https://github.com/user/skills-manager
+Project-URL: Issues, https://github.com/user/skills-manager/issues
+Author: Skills Manager Team
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,function-calling,gemini,mcp,openai,skill,tool
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: recommend
+Requires-Dist: jieba>=0.42.1; extra == 'recommend'
+Provides-Extra: remote
+Requires-Dist: httpx>=0.24.0; extra == 'remote'
+Description-Content-Type: text/markdown
+
+# Skills Manager
+
+> 用一种极简格式定义 AI Skill，一键导出为 OpenAI / Claude / Gemini / MCP 等主流平台格式。
+
+## 核心理念
+
+**不要做 Skill 的 npm，做 Skill 的 babel。**
+
+AI Agent 生态的工具格式碎片化，同一个能力要在每个平台手写一遍定义。Skills Manager 让你只写一次，到处导出。
+
+## 项目状态
+
+- **测试覆盖率**：92%
+- **测试数量**：144 个（全部通过）
+- **支持格式**：5 种（OpenAI / Claude / Gemini / MCP / JSON Schema）
+- **平台打包**：3 种（Claude Desktop / Codex / Claude Code）
+
+## 功能特性
+
+### 核心功能
+
+- **格式转换**：一份定义 → 多平台格式（OpenAI / Claude / Gemini / MCP / JSON Schema）
+- **可视化管理**：桌面客户端提供直观的 Skill 浏览、搜索、编辑和导出体验
+- **本地管理**：所有 Skill 统一存储，安装、搜索、查看一条命令或一次点击搞定
+- **自动同步**：安装后自动 symlink 到各 agent 目录，agent 立即可用
+- **格式验证**：安装前自动验证 SKILL.md 格式，确保合规
+
+### 桌面客户端
+
+- **Skill 浏览**：卡片式浏览、分类筛选、关键词搜索
+- **类型筛选**：按 component / interactive / workflow 语义类型筛选
+- **一键导出**：选中 Skill → 选择目标平台 → 复制或保存
+- **批量导出**：多选 Skill 批量导出
+- **平台打包**：导出为 Claude Desktop / Codex / Claude Code 平台格式
+- **安装管理**：从目录、.skill 包、自动扫描导入
+- **主题切换**：浅色 / 深色主题
+- **监视路径**：自定义扫描路径
+
+### CLI 工具
+
+```bash
+# Skill 管理
+skills-manager install <source>              # 安装（目录 / .skill 包）
+skills-manager uninstall <name>              # 卸载
+skills-manager list                          # 列出已安装
+skills-manager info <name>                   # 查看详情
+
+# 格式导出
+skills-manager export <name> --format openai|claude|gemini|mcp|schema
+skills-manager export --all --format openai  # 批量导出
+
+# 打包
+skills-manager pack <dir>                    # 打包为 .skill 文件
+```
+
+## 安装
+
+### 从源码安装
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd skills-manager-prototype
+
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# 或
+.venv\Scripts\activate     # Windows
+
+# 安装依赖
+pip install -e ".[dev]"
+```
+
+### 运行桌面应用
+
+```bash
+python -m desktop.main
+```
+
+### 运行 CLI
+
+```bash
+skills-manager --help
+```
+
+## 快速开始
+
+### 1. 创建一个 Skill
+
+创建目录 `my-skill/`，在其中创建 `SKILL.md`：
+
+```markdown
+---
+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"}
+```
+
+```json
+{"greeting": "你好，世界！"}
+```
+
+## 适用场景
+
+- 测试 Skill 系统
+- 演示基本功能
+
+## 不适用
+
+- 生产环境使用
+```
+
+### 2. 安装 Skill
+
+```bash
+# 从目录安装
+skills-manager install ./my-skill
+
+# 或使用桌面应用
+# 点击侧边栏"安装 Skill" → 选择目录
+```
+
+### 3. 导出 Skill
+
+```bash
+# 导出为 OpenAI 格式
+skills-manager export hello --format openai
+
+# 导出为 Claude 格式
+skills-manager export hello --format claude
+
+# 导出为 MCP Server
+skills-manager export hello --format mcp --output hello_mcp.py
+```
+
+### 4. 使用桌面应用
+
+```bash
+python -m desktop.main
+```
+
+在桌面应用中：
+1. 浏览已安装的 Skill
+2. 点击 Skill 查看详情
+3. 选择格式导出
+4. 或批量导出多个 Skill
+
+## SKILL.md 格式规范
+
+### Frontmatter（必填）
+
+```yaml
+---
+name: skill-name          # 必填：唯一标识，小写 + 连字符
+version: "1.0.0"          # 必填：语义化版本
+description: 一句话描述    # 必填：简短描述（< 200 字）
+summary: |                # 必填：2-3 句话摘要
+  详细描述这个 Skill 的功能。
+  支持多行文本。
+---
+```
+
+### Frontmatter（可选）
+
+```yaml
+---
+# 语义类型
+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
+
+```markdown
+## 功能
+
+详细描述 Skill 的功能。
+
+## 参数
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| param1 | string | ✅ | 参数说明 |
+| param2 | integer | ❌ | 可选参数 |
+
+## 返回
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| result | string | 返回结果 |
+
+## 示例
+
+输入：
+```json
+{"param1": "value"}
+```
+
+输出：
+```json
+{"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-prototype/
+├── README.md                           # 本文件
+├── IMPROVEMENTS.md                     # 改进计划
+├── pyproject.toml                      # 项目配置
+├── src/skills_manager/                 # 核心引擎
+│   ├── __init__.py
+│   ├── ir.py                           # 中间表示（IR）
+│   ├── parser.py                       # SKILL.md 解析器
+│   ├── store.py                        # 本地存储管理
+│   ├── validator.py                    # 格式验证器
+│   ├── packager.py                     # 打包器
+│   ├── agent_config.py                 # Agent 配置生成
+│   ├── cli.py                          # CLI 入口
+│   └── adapters/                       # 格式适配器
+│       ├── base.py                     # 适配器基类
+│       ├── openai.py                   # OpenAI 适配器
+│       ├── claude.py                   # Claude 适配器
+│       ├── gemini.py                   # Gemini 适配器
+│       ├── mcp.py                      # MCP 适配器
+│       └── json_schema.py             # JSON Schema 适配器
+├── desktop/                            # 桌面客户端（Flet）
+│   ├── main.py                         # 入口
+│   ├── app.py                          # 主控类
+│   ├── components.py                   # 可复用组件
+│   ├── dialogs.py                      # 对话框
+│   └── pages/                          # 页面
+│       ├── browse.py                   # 浏览页
+│       ├── detail.py                   # 详情页
+│       ├── export.py                   # 导出页
+│       ├── editor.py                   # 编辑器页
+│       └── settings.py                 # 设置页
+├── examples/                           # 示例 Skills
+│   ├── translator/                     # 翻译工具（component）
+│   ├── json-formatter/                 # JSON 格式化（component）
+│   ├── code-reviewer/                  # 代码审查（component）
+│   ├── interview-prep/                 # 面试准备（interactive）
+│   ├── deploy-pipeline/                # 部署流程（workflow）
+│   └── code-generator/                 # 代码生成（component）
+└── tests/                              # 测试
+    ├── test_parser.py
+    ├── test_adapters.py
+    ├── test_store.py
+    ├── test_validator.py
+    ├── test_packager.py
+    ├── test_agent_config.py
+    └── test_cli.py
+```
+
+## 开发指南
+
+### 运行测试
+
+```bash
+# 运行所有测试
+pytest tests/
+
+# 运行特定测试
+pytest tests/test_parser.py -v
+
+# 查看覆盖率
+pytest tests/ --cov=skills_manager --cov-report=term-missing
+```
+
+### 代码质量
+
+```bash
+# 格式化
+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. 添加测试用例
+
+## 文档
+
+- [任务书](../task-book.md) — 解决什么问题、做什么不做什么、路线图
+- [技术设计文档](../tech-design.md) — 格式规范、IR、适配器、CLI、存储、实现细节
+- [改进计划](./IMPROVEMENTS.md) — 参考 Product Manager Skills 的改进方向
+- [用户指南](./docs/user-guide.md) — 详细使用说明
+
+## 许可
+
+MIT

skillfmt-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+skills_manager/__init__.py,sha256=nhGLnWOM7Z7HmmxkczWrmc3ggyvjKWqZZ3N-dPJAmEI,83
+skills_manager/agent_config.py,sha256=dTO2wXVCMKn8qxej7GCJqKbn7tXreuIsb8TMybdLWdU,1910
+skills_manager/claude_code_checker.py,sha256=MET5z8bLRFdkB8eZzAHFYxMP8ilxbt6L6B8ajL_CfZA,7078
+skills_manager/cli.py,sha256=W8JunTY7MZHaws7M3XyNa4jKC5B5bwh_ws94csFW4ow,13810
+skills_manager/ir.py,sha256=dbG0cV5kKhCF4CE9G4EYQDf9G96dXAtXQiegeK0Rvuw,2004
+skills_manager/logging.py,sha256=jgbvWVHr2ABDbuC73LNUsiF0vXMSU_RUIJ2PxuGUFNA,3449
+skills_manager/packager.py,sha256=gvpbdMA1eCpnDDax-gMRnIv8Rf_9rc__hwWthGaZwT4,6244
+skills_manager/parser.py,sha256=HWtlcTLgtO5KdVzH_sPhq2p5SKoTXS7m6wSEqk3yBk4,9415
+skills_manager/recommend.py,sha256=QQ0I-O8pyXomlmtMftJoquDW-cwDdYt7am5urqehscs,4320
+skills_manager/security.py,sha256=dfhvrHgpHgIK6Dys1RYpxKXGOancH4RjpkGJd_gCPBw,2223
+skills_manager/store.py,sha256=DaRF0T6Bj5iSFKITg4Jy-3EvWL9nRLumy36-fGb-eZg,43216
+skills_manager/validator.py,sha256=9HHhd1TOkTKvT_ycVjkRuMKU0NCmnuBpHnPniQi0Wzs,4770
+skills_manager/adapters/__init__.py,sha256=fNBcFT52Idek9jQ1SZcwkUif1Zpr7A22ewGf2KjRQ3E,518
+skills_manager/adapters/base.py,sha256=CiOwfn-c8i5MxIpqfFkboxLa8f0klAcbGNCKoRq6YWY,2291
+skills_manager/adapters/claude.py,sha256=xgJ8q9-hRrV0_HG-40uaG3WpoMuukHcA9-9bm8zG7Uo,765
+skills_manager/adapters/gemini.py,sha256=fxmQbUvyK_Eb3s7-8QD721MxLQnFDH4ttvKhWjxcHHA,1784
+skills_manager/adapters/json_schema.py,sha256=6PXkOF5lUXYUn_Kx0YfFOBZYeTaG0BdBdC2rejWo0eE,822
+skills_manager/adapters/mcp.py,sha256=exNZ707JzjlsyxI6faAQC5YJbWq4uU4zhmN1XrQr0TE,1717
+skills_manager/adapters/openai.py,sha256=eOodBgYqXQ1NHtwj04Sx83e4enhkux2jWAmwV-1x4Oo,896
+skillfmt-0.1.0.dist-info/METADATA,sha256=LePTqcuiYma7Byz_exnGzbe4IBr-CqLLz7leGH23XtA,11078
+skillfmt-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+skillfmt-0.1.0.dist-info/entry_points.txt,sha256=OVPC7Bva9eiz9om9CKZLUWuNiBT2Qhus3_68m-ma-Fw,84
+skillfmt-0.1.0.dist-info/licenses/LICENSE,sha256=xD7f3ZoUZ59bb8JFD-Ew4Jcxuj-rcyF8gVLwlBqCPI4,1071
+skillfmt-0.1.0.dist-info/RECORD,,

skillfmt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

skillfmt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+skillfmt = skills_manager.cli:app
+skills = skills_manager.cli:app

skillfmt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skills Manager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Skills Manager - AI Skill 格式转换与管理工具"""
+
+__version__ = "0.1.0"

skills_manager/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""适配器模块。
+
+将 SkillIR 转换为各平台的工具定义格式。
+"""
+
+from .base import Adapter, AdapterError, get_adapter, list_formats
+from .claude import ClaudeAdapter
+from .gemini import GeminiAdapter
+from .json_schema import JsonSchemaAdapter
+from .mcp import MCPAdapter
+from .openai import OpenAIAdapter
+
+__all__ = [
+    "Adapter",
+    "AdapterError",
+    "get_adapter",
+    "list_formats",
+    "OpenAIAdapter",
+    "ClaudeAdapter",
+    "GeminiAdapter",
+    "MCPAdapter",
+    "JsonSchemaAdapter",
+]

skills_manager/adapters/base.py

@@ -0,0 +1,92 @@
+"""适配器基类与注册。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..ir import SkillIR
+
+
+class AdapterError(Exception):
+    """适配器错误。"""
+
+
+class Adapter(ABC):
+    """所有适配器的基类。"""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """适配器名称，如 'openai', 'claude'。"""
+        ...
+
+    @property
+    @abstractmethod
+    def file_extension(self) -> str:
+        """输出文件扩展名，如 '.json', '.py'。"""
+        ...
+
+    @abstractmethod
+    def export(self, ir: SkillIR) -> str:
+        """将 IR 转换为目标格式的字符串。"""
+        ...
+
+    def export_batch(self, irs: list[SkillIR]) -> str:
+        """批量导出多个 IR。"""
+        import json
+
+        results = []
+        for ir in irs:
+            content = self.export(ir)
+            try:
+                results.append(json.loads(content))
+            except json.JSONDecodeError:
+                results.append(content)
+        return json.dumps(results, indent=2, ensure_ascii=False)
+
+
+# 适配器注册表
+_REGISTRY: dict[str, Adapter] = {}
+
+
+def register(adapter: Adapter) -> None:
+    """注册适配器。"""
+    _REGISTRY[adapter.name] = adapter
+
+
+def get_adapter(format_name: str) -> Adapter:
+    """获取指定格式的适配器。
+
+    Raises:
+        ValueError: 不支持的格式。
+    """
+    _ensure_registered()
+    if format_name not in _REGISTRY:
+        available = ", ".join(sorted(_REGISTRY.keys()))
+        raise ValueError(f"Unsupported format: {format_name}. Available: {available}")
+    return _REGISTRY[format_name]
+
+
+def list_formats() -> list[str]:
+    """列出所有支持的格式。"""
+    _ensure_registered()
+    return sorted(_REGISTRY.keys())
+
+
+def _ensure_registered() -> None:
+    """确保所有内置适配器已注册。"""
+    if _REGISTRY:
+        return
+    from .claude import ClaudeAdapter
+    from .gemini import GeminiAdapter
+    from .json_schema import JsonSchemaAdapter
+    from .mcp import MCPAdapter
+    from .openai import OpenAIAdapter
+
+    register(OpenAIAdapter())
+    register(ClaudeAdapter())
+    register(GeminiAdapter())
+    register(MCPAdapter())
+    register(JsonSchemaAdapter())

skills_manager/adapters/claude.py

@@ -0,0 +1,33 @@
+"""Claude Tool Use 格式适配器。"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .base import Adapter
+from ..parser import parameters_to_json_schema
+
+if TYPE_CHECKING:
+    from ..ir import SkillIR
+
+
+class ClaudeAdapter(Adapter):
+    """Claude Tool Use 格式适配器。"""
+
+    @property
+    def name(self) -> str:
+        return "claude"
+
+    @property
+    def file_extension(self) -> str:
+        return ".json"
+
+    def export(self, ir: SkillIR) -> str:
+        schema = parameters_to_json_schema(ir.parameters)
+        result = {
+            "name": ir.name,
+            "description": ir.description,
+            "input_schema": schema,
+        }
+        return json.dumps(result, indent=2, ensure_ascii=False)

skills_manager/adapters/gemini.py

@@ -0,0 +1,68 @@
+"""Gemini Function Declaration 格式适配器。"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .base import Adapter
+from ..ir import Parameter
+
+if TYPE_CHECKING:
+    from ..ir import SkillIR
+
+
+# JSON Schema 类型 → Gemini 类型
+GEMINI_TYPE_MAP = {
+    "string": "STRING",
+    "integer": "INTEGER",
+    "number": "NUMBER",
+    "boolean": "BOOLEAN",
+    "array": "ARRAY",
+    "object": "OBJECT",
+}
+
+
+class GeminiAdapter(Adapter):
+    """Gemini Function Declaration 格式适配器。"""
+
+    @property
+    def name(self) -> str:
+        return "gemini"
+
+    @property
+    def file_extension(self) -> str:
+        return ".json"
+
+    def export(self, ir: SkillIR) -> str:
+        params = self._parameters_to_schema(ir.parameters)
+        result = {
+            "function_declarations": [
+                {
+                    "name": ir.name,
+                    "description": ir.description,
+                    "parameters": params,
+                }
+            ]
+        }
+        return json.dumps(result, indent=2, ensure_ascii=False)
+
+    def _parameters_to_schema(self, parameters: list[Parameter]) -> dict:
+        """将参数转换为 Gemini 格式的 schema（类型名大写）。"""
+        properties = {}
+        required = []
+
+        for p in parameters:
+            gemini_type = GEMINI_TYPE_MAP.get(p.type, "STRING")
+            prop: dict = {"type": gemini_type, "description": p.description}
+            if p.enum:
+                prop["enum"] = p.enum
+            properties[p.name] = prop
+            if p.required:
+                required.append(p.name)
+
+        schema: dict = {"type": "OBJECT", "properties": properties}
+        if required:
+            schema["required"] = required
+
+        return schema