Skill-Cortex (Lite) / Skill-Cortex (精简版)

一个第三方 MCP 服务器：让所有 IDE 获得 Claude Code Skills 的能力。

A third-party MCP server: Enable all IDEs to access Claude Code Skills capabilities.

Features / 特性

• Skill Discovery & Indexing / 技能发现与索引: Automatically scan and index SKILL.md files from multiple sources / 自动扫描和索引来自多个来源的 SKILL.md 文件
• Flexible Configuration / 灵活配置: Support for custom skill roots and cache paths / 支持自定义技能根目录和缓存路径
• Tag Management / 标签管理: Built-in tag validation and management system / 内置标签验证和管理系统
• Skill Tree Navigation / 技能树导航: Hierarchical browsing of skills by category / 按类别分层浏览技能
• Search Functionality / 搜索功能: Full-text search across all indexed skills / 对所有索引技能进行全文搜索
• Skill Details / 技能详情: Detailed information retrieval for each skill / 每个技能的详细信息检索
• Enhanced Import Tools / 增强导入工具: Advanced import script with configuration files, progress tracking, and robust error handling / 具有配置文件、进度跟踪和健壮错误处理的高级导入脚本
• No Bundled Skills in Repo / 仓库不内置 Skills: This repository does not ship skills by default; put your skills under ~/.claude/skills or ./.skills / 本仓库默认不内置 skills，请将 skills 放到 ~/.claude/skills 或 ./.skills
• Context Compression / 上下文压缩: Token-friendly skill retrieval with section-based extraction (summary, instructions, examples, full) / 支持按 section 提取技能内容，节省 token 消耗

Prerequisites / 先决条件

• Python 3.11 or higher / Python 3.11 或更高版本
• pip package manager / pip 包管理器

Key Technologies / 关键技术

• MCP (Model Context Protocol): For server integration / 用于服务器集成
• Python Standard Library: File system operations and caching / 文件系统操作和缓存

Project Structure / 项目结构

skill_cortex_server/
├── skill_cortex/              # Main package / 主包
│   ├── __init__.py           # Package initialization / 包初始化
│   ├── server.py             # MCP server implementation / MCP 服务器实现
│   ├── models.py             # Data models / 数据模型
│   ├── config.py             # Configuration management / 配置管理
│   ├── scanner.py            # Skill file scanner / 技能文件扫描器
│   ├── index_store.py        # Index storage and caching / 索引存储和缓存
│   ├── tags_registry.py      # Tag management system / 标签管理系统
│   └── frontmatter.py        # Frontmatter parsing / 前置元数据解析
├── config/                    # Configuration files / 配置文件
│   └── examples/             # Example configuration files / 示例配置文件
│       ├── skills-config.yaml # YAML configuration example / YAML配置示例
│       └── skills-config.json # JSON configuration example / JSON配置示例
├── .kiro/                     # Kiro specs and development files / Kiro规范和开发文件
│   └── specs/                # Feature specifications / 功能规范
├── .skill_cortex_cache/       # Cache directory / 缓存目录
│   └── index.json            # Skill index cache / 技能索引缓存
├── .skill_cortex_sources/     # Imported skills source / 导入的技能源
├── .skills/                   # Local skills directory / 本地技能目录
│   └── imported/             # Imported skills / 导入的技能
├── import_skills.py          # Enhanced skill import script / 增强的技能导入脚本
├── pyproject.toml            # Project configuration / 项目配置
├── README.md                 # This file / 本文件
└── tags.md                   # Allowed tags list / 允许的标签列表

Quick Start / 快速开始

Installation / 安装

# Install in editable mode / 以可编辑模式安装
pip install -e .

# Or install from PyPI (when available) / 或从 PyPI 安装（当可用时）
pip install skill-cortex-lite

Run the Server / 运行服务器

# Run directly / 直接运行
skill-cortex

# Or use Python module / 或使用 Python 模块
python -m skill_cortex.server

MCP Tools / MCP 工具

1. list_skill_tree / 列出技能树

Browse skills in a hierarchical tree structure / 以分层树结构浏览技能

Parameters / 参数:

• path (optional): Starting path in the skill tree / 技能树中的起始路径

Example / 示例:

{
  "path": "coding"
}

Response / 响应: Returns a hierarchical tree of skills with their metadata / 返回包含元数据的分层技能树

2. search_skills / 搜索技能

Search for skills by query text / 通过查询文本搜索技能

Parameters / 参数:

• query (optional): Search query string / 搜索查询字符串
• tags (optional): Array of tags to filter by / 用于筛选的标签数组

Example / 示例:

{
  "query": "database",
  "tags": ["coding", "data"]
}

Response / 响应: Returns matching skills with their details / 返回匹配的技能及其详细信息

3. get_skill_details / 获取技能详情

Get detailed information about a specific skill with context compression / 获取特定技能的详细信息，支持上下文压缩

Parameters / 参数:

• skill_id (required): Unique identifier of the skill / 技能的唯一标识符
• section (optional): What to return / 返回内容类型
  • "summary" (default): Frontmatter + description snapshot (token-friendly) / 仅元数据和描述摘要（节省token）
  • "instructions": Main instructions section only / 仅主要指令部分
  • "examples": Code examples section only / 仅代码示例部分
  • "full": Complete SKILL.md content / 完整内容
• max_lines (optional): Limit output to N lines / 限制输出行数

Example / 示例:

{
  "skill_id": "coding/database/query",
  "section": "summary"
}

{
  "skill_id": "coding/database/query",
  "section": "instructions",
  "max_lines": 50
}

Response / 响应: Returns skill information based on section parameter / 根据 section 参数返回技能信息

4. update_tags / 更新标签

Manage tags inside skills frontmatter / 管理 skills 的 frontmatter tags

Parameters / 参数:

• mode (required): "list" or "apply" / 操作模式："list" 或 "apply"
• updates (optional): required when mode is "apply" / 当 mode 为 "apply" 时需要提供

Example / 示例:

{
  "mode": "list"
}

{
  "mode": "apply",
  "updates": [
    {"skill_id": "...", "tags": ["python", "mcp"]}
  ]
}

Response / 响应: Returns the current tags list or operation result / 返回当前标签列表或操作结果

5. create_new_skill / 创建新技能

Create a new skill with automatic validation and indexing / 创建新技能并自动验证和索引

Parameters / 参数:

• path (required): Skill path (e.g., "coding/python-helper" or "simple-skill") / 技能路径
• description (required): Skill description (1-1024 characters) / 技能描述（1-1024字符）
• tags (optional): Array of tags / 标签数组
• instructions (optional): Custom instructions (if not provided, a template will be generated) / 自定义指令（如未提供则生成模板）
• license (optional): License information / 许可证信息
• metadata (optional): Metadata dict (e.g., {"author": "example", "version": "1.0"}) / 元数据字典
• create_scripts_dir (optional): Whether to create scripts/ directory / 是否创建 scripts/ 目录
• create_references_dir (optional): Whether to create references/ directory / 是否创建 references/ 目录
• create_assets_dir (optional): Whether to create assets/ directory / 是否创建 assets/ 目录

Example / 示例:

{
  "path": "coding/python-helper",
  "description": "A helper skill for Python development tasks",
  "tags": ["python", "coding", "development"],
  "create_scripts_dir": true
}

{
  "path": "simple-skill",
  "description": "A simple skill example",
  "tags": ["example"],
  "instructions": "## Instructions\n\nDetailed instructions here...",
  "metadata": {"author": "example-user", "version": "1.0"}
}

Response / 响应: Returns creation result with skill path and details / 返回创建结果，包含技能路径和详细信息

Notes / 注意事项:

• Skills are created in the .skills/ directory / 技能创建在 .skills/ 目录中
• Skill names must be lowercase with hyphens only / 技能名称必须是小写字母和连字符
• Supports category paths (e.g., "coding/python-helper") / 支持分类路径
• Automatically validates name format and updates index / 自动验证名称格式并更新索引

6. delete_existing_skill / 删除现有技能

Delete a user-created skill (requires confirmation) / 删除用户创建的技能（需要确认）

Parameters / 参数:

• skill_id (required): Unique identifier of the skill to delete / 要删除的技能的唯一标识符
• confirm (required): Must be True to actually delete (False shows preview only) / 必须为 True 才能实际删除（False 仅显示预览）

Example / 示例:

{
  "skill_id": ".skills:coding/python-helper/SKILL.md",
  "confirm": false
}

{
  "skill_id": ".skills:simple-skill/SKILL.md",
  "confirm": true
}

Response / 响应: Returns deletion result or preview information / 返回删除结果或预览信息

Safety Features / 安全特性:

• Only allows deletion of skills in .skills/ directory / 仅允许删除 .skills/ 目录中的技能
• Cannot delete imported skills (.skills/imported/) / 无法删除导入的技能
• Cannot delete source repository skills (.skill_cortex_sources/) / 无法删除源仓库技能
• Requires explicit confirm=true to execute deletion / 需要显式 confirm=true 才能执行删除
• Automatically updates index after deletion / 删除后自动更新索引

Configuration / 配置

Environment Variables / 环境变量

• SKILL_CORTEX_ROOTS: Comma-separated list of skill root directories / 逗号分隔的技能根目录列表

  • Default: ~/.claude/skills,./.skills / 默认值
  • Example: /path/to/skills1,/path/to/skills2 / 示例

• SKILL_CORTEX_CACHE_PATH: Path to the index cache file / 索引缓存文件路径

  • Default: ./.skill_cortex_cache/index.json / 默认值
  • Example: /custom/path/cache.json / 示例

• SKILL_CORTEX_TAGS_PATH: Path to the allowed tags file / 允许的标签文件路径

  • Default: ./tags.md / 默认值
  • Example: /custom/path/tags.md / 示例

Example Configuration / 配置示例

{
  "mcpServers": {
    "skill-cortex-lite": {
      "command": "skill-cortex",
      "args": [],
      "env": {
        "SKILL_CORTEX_ROOTS": "/Users/username/skills1,/Users/username/skills2",
        "SKILL_CORTEX_CACHE_PATH": "/Users/username/.skill_cortex_cache/index.json",
        "SKILL_CORTEX_TAGS_PATH": "/Users/username/tags.md"
      }
    }
  }
}

Importing Skills / 导入技能

The project includes an enhanced import script with advanced features for importing skills from public repositories / 项目包含一个增强的导入脚本，具有从公共仓库导入技能的高级功能

Enhanced Import Features / 增强导入功能

🔧 Configuration File Support / 配置文件支持

• YAML/JSON Configuration: Use configuration files to customize repository lists without modifying code / 使用配置文件自定义仓库列表，无需修改代码
• Auto-discovery: Automatically finds skills-config.yaml, skills-config.yml, or skills-config.json in current directory / 自动查找当前目录中的配置文件
• Custom config path: Use --config option to specify custom configuration file / 使用 --config 选项指定自定义配置文件