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 选项指定自定义配置文件

📊 Progress Display / 进度显示

• Real-time progress: Shows current repository being processed with step-by-step feedback / 显示当前处理的仓库和逐步反馈
• Skill counting: Displays number of skills found in each repository / 显示每个仓库中找到的技能数量
• Comprehensive summary: Final report with statistics, timing, and success/failure counts / 包含统计、时间和成功/失败计数的最终报告

🛡️ Robust Error Handling / 健壮错误处理

• Continue on error: Single repository failure doesn't stop the entire import process / 单个仓库失败不会停止整个导入过程
• Detailed error reporting: Clear error messages with specific failure reasons / 清晰的错误消息和具体失败原因
• Error categorization: Different handling for network, file system, and Git errors / 对网络、文件系统和Git错误的不同处理

🔍 Enhanced Preview Mode / 增强预览模式

• Detailed dry-run: Shows repository URLs, skill paths, and counts before actual import / 在实际导入前显示仓库URL、技能路径和计数
• Clear indicators: Clearly shows when running in preview mode with no actual changes / 清楚显示预览模式，不进行实际更改

Built-in Skills / 内置技能

This repository does not bundle skills by default. Use the import script (optional) to fetch skills from public repositories / 本仓库默认不内置 skills，可使用导入脚本（可选）从公共仓库拉取：

1. agentskills/agentskills

A comprehensive collection of AI agent skills and capabilities / 一个全面的 AI 代理技能和能力集合

• Features / 特性: Provides a wide range of skills for AI agents, including coding, data analysis, and problem-solving / 为 AI 代理提供广泛的技能，包括编码、数据分析和问题解决
• Skill Types / 技能类型: Coding, debugging, testing, optimization, and more / 编码、调试、测试、优化等
• Usage / 用途: Enhances AI agent capabilities with practical, reusable skills / 通过实用的、可重用的技能增强 AI 代理能力

2. anthropics/skills

Official skills repository from Anthropic / Anthropic 的官方技能仓库

• Features / 特性: Officially maintained skills optimized for Claude AI / 官方维护的针对 Claude AI 优化的技能
• Skill Types / 技能类型: Documentation, code generation, system administration, and more / 文档、代码生成、系统管理等
• Usage / 用途: Provides high-quality, tested skills for production use / 为生产环境提供高质量、经过测试的技能

3. ComposioHQ/awesome-claude-skills

Community-curated collection of Claude Skills resources / 社区策划的Claude Skills资源集合

• Features / 特性: Curated list of awesome Claude Skills, resources, and tools / 精选的Claude Skills、资源和工具列表
• Skill Types / 技能类型: Various community-contributed skills and resources / 各种社区贡献的技能和资源
• Usage / 用途: Access to community-driven skill collections / 访问社区驱动的技能集合

4. huggingface/skills

Hugging Face's skills repository for AI and machine learning / Hugging Face 的 AI 和机器学习技能仓库

• Features / 特性: Skills and tools for working with Hugging Face ecosystem / 用于 Hugging Face 生态系统的技能和工具
• Skill Types / 技能类型: Machine learning, model training, dataset handling, and more / 机器学习、模型训练、数据处理等
• Usage / 用途: Enhances capabilities for AI/ML tasks and Hugging Face integrations / 增强 AI/ML 任务和 Hugging Face 集成的能力

Import Script Usage / 导入脚本使用

Basic Usage / 基本使用

# Preview what would be imported (recommended first step) / 预览将要导入的内容（推荐第一步）
python import_skills.py --dry-run

# Actually import the skills / 实际导入技能
python import_skills.py

# Clean import (remove existing skills first) / 清理导入（先删除现有技能）
python import_skills.py --clean

Advanced Usage / 高级使用

# Use custom configuration file / 使用自定义配置文件
python import_skills.py --config my-config.yaml

# Import only specific repositories / 仅导入特定仓库
python import_skills.py --only anthropics_skills --only agentskills_agentskills

# Skip cloning (use existing local repositories) / 跳过克隆（使用现有本地仓库）
python import_skills.py --no-clone

# Don't update existing repositories / 不更新现有仓库
python import_skills.py --no-update

Configuration File Examples / 配置文件示例

YAML Configuration (skills-config.yaml):

repositories:
  - name: "anthropics_skills"
    url: "https://github.com/anthropics/skills.git"
    enabled: true
    
  - name: "agentskills_agentskills"
    url: "https://github.com/agentskills/agentskills.git"
    enabled: true
    
  - name: "composio_awesome_skills"
    url: "https://github.com/ComposioHQ/awesome-claude-skills.git"
    enabled: true
    
  - name: "huggingface_skills"
    url: "https://github.com/huggingface/skills.git"
    enabled: true

settings:
  incremental: false
  validation: false

JSON Configuration (skills-config.json):

{
  "repositories": [
    {
      "name": "anthropics_skills",
      "url": "https://github.com/anthropics/skills.git",
      "enabled": true
    },
    {
      "name": "agentskills_agentskills",
      "url": "https://github.com/agentskills/agentskills.git",
      "enabled": true
    },
    {
      "name": "composio_awesome_skills",
      "url": "https://github.com/ComposioHQ/awesome-claude-skills.git",
      "enabled": true
    },
    {
      "name": "huggingface_skills",
      "url": "https://github.com/huggingface/skills.git",
      "enabled": true
    }
  ],
  "settings": {
    "incremental": false,
    "validation": false
  }
}

Import Process / 导入过程

Skills are imported to: ./.skill_cortex_sources/ / 技能导入到：./.skill_cortex_sources/

Skills are copied to: ./.skills/imported/ / 技能拷贝到：./.skills/imported/

The import process includes:

1. Repository cloning/updating / 仓库克隆/更新
2. Skill discovery / 技能发现
3. File copying / 文件复制
4. Progress reporting / 进度报告
5. Error handling / 错误处理

Troubleshooting / 故障排除

ModuleNotFoundError / 模块未找到错误

Problem / 问题:

ModuleNotFoundError: No module named 'skill_cortex'

Solution / 解决方案: Install the package in editable mode / 以可编辑模式安装包

pip install -e .

Skills not appearing / 技能未显示

Problem / 问题: Skills are not showing up in the tool results / 技能未在工具结果中显示

Solution / 解决方案:

1. Check that SKILL_CORTEX_ROOTS points to correct directories / 检查 SKILL_CORTEX_ROOTS 是否指向正确的目录
2. Verify that SKILL.md files exist in those directories / 验证这些目录中是否存在 SKILL.md 文件
3. Clear the cache by deleting the index.json file / 通过删除 index.json 文件清除缓存
4. Restart the server / 重启服务器

Tag validation errors / 标签验证错误

Problem / 问题: Tags are being rejected / 标签被拒绝

Solution / 解决方案:

1. Check the tags.md file for the allowed tags list / 检查 tags.md 文件中的允许标签列表
2. Use the update_tags tool to add missing tags / 使用 update_tags 工具添加缺失的标签
3. Ensure tag names match exactly (case-sensitive) / 确保标签名称完全匹配（区分大小写）

Import script errors / 导入脚本错误

Problem / 问题: Import script fails with configuration or repository errors / 导入脚本因配置或仓库错误而失败

Solution / 解决方案:

1. Use --dry-run first to preview what will be imported / 首先使用 --dry-run 预览将要导入的内容
2. Check configuration file syntax if using custom config / 如果使用自定义配置，检查配置文件语法
3. Verify repository URLs are accessible / 验证仓库URL是否可访问
4. Use --no-clone to skip cloning if repositories already exist locally / 如果仓库已存在本地，使用 --no-clone 跳过克隆
5. Check the detailed error report in the final summary / 检查最终摘要中的详细错误报告

Development / 开发

Project Setup / 项目设置

# Clone the repository / 克隆仓库
git clone <repository-url>
cd skill_cortex_server

# Install in development mode / 以开发模式安装
pip install -e .

Running Tests / 运行测试

# Run all tests / 运行所有测试
pytest

# Run with coverage / 运行并生成覆盖率报告
pytest --cov=skill_cortex

Contributing / 贡献

Contributions are welcome! Please feel free to submit a Pull Request / 欢迎贡献！请随时提交 Pull Request

1. Fork the repository / Fork 仓库
2. Create your feature branch / 创建功能分支
3. Commit your changes / 提交更改
4. Push to the branch / 推送到分支
5. Open a Pull Request / 打开 Pull Request

License / 许可证

This project is licensed under the MIT License / 本项目采用 MIT 许可证

Acknowledgments / 致谢

• Inspired by Claude Code Skills / 灵感来自 Claude Code Skills
• Built with MCP (Model Context Protocol) / 使用 MCP（模型上下文协议）构建
• Reference implementation based on mcp-sequential-thinking / 基于 mcp-sequential-thinking 的参考实现

Contact / 联系方式

For questions and support, please open an issue on GitHub / 如有问题和支持需求，请在 GitHub 上提交 issue