一个第三方 MCP 服务器：让所有 IDE 获得 Claude Code Skills 的能力。 A third-party MCP server: Enable all IDEs to access Claude Code Skills capabilities. - 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
Add this skill
npx mdskills install Sim-xia/skill-cortex-serverWell-architected MCP server providing comprehensive skill indexing, search, and management with context compression
1# Skill-Cortex (Lite) / Skill-Cortex (精简版)23一个第三方 MCP 服务器：让所有 IDE 获得 Claude Code Skills 的能力。45A third-party MCP server: Enable all IDEs to access Claude Code Skills capabilities.67## Features / 特性89- **Skill Discovery & Indexing / 技能发现与索引**: Automatically scan and index SKILL.md files from multiple sources / 自动扫描和索引来自多个来源的 SKILL.md 文件10- **Flexible Configuration / 灵活配置**: Support for custom skill roots and cache paths / 支持自定义技能根目录和缓存路径11- **Tag Management / 标签管理**: Built-in tag validation and management system / 内置标签验证和管理系统12- **Skill Tree Navigation / 技能树导航**: Hierarchical browsing of skills by category / 按类别分层浏览技能13- **Search Functionality / 搜索功能**: Full-text search across all indexed skills / 对所有索引技能进行全文搜索14- **Skill Details / 技能详情**: Detailed information retrieval for each skill / 每个技能的详细信息检索15- **Enhanced Import Tools / 增强导入工具**: Advanced import script with configuration files, progress tracking, and robust error handling / 具有配置文件、进度跟踪和健壮错误处理的高级导入脚本16- **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`17- **Context Compression / 上下文压缩**: Token-friendly skill retrieval with section-based extraction (summary, instructions, examples, full) / 支持按 section 提取技能内容，节省 token 消耗1819## Prerequisites / 先决条件2021- Python 3.11 or higher / Python 3.11 或更高版本22- pip package manager / pip 包管理器2324## Key Technologies / 关键技术2526- **MCP (Model Context Protocol)**: For server integration / 用于服务器集成27- **Python Standard Library**: File system operations and caching / 文件系统操作和缓存2829## Project Structure / 项目结构3031```32skill_cortex_server/33├── skill_cortex/ # Main package / 主包34│ ├── __init__.py # Package initialization / 包初始化35│ ├── server.py # MCP server implementation / MCP 服务器实现36│ ├── models.py # Data models / 数据模型37│ ├── config.py # Configuration management / 配置管理38│ ├── scanner.py # Skill file scanner / 技能文件扫描器39│ ├── index_store.py # Index storage and caching / 索引存储和缓存40│ ├── tags_registry.py # Tag management system / 标签管理系统41│ └── frontmatter.py # Frontmatter parsing / 前置元数据解析42├── config/ # Configuration files / 配置文件43│ └── examples/ # Example configuration files / 示例配置文件44│ ├── skills-config.yaml # YAML configuration example / YAML配置示例45│ └── skills-config.json # JSON configuration example / JSON配置示例46├── .kiro/ # Kiro specs and development files / Kiro规范和开发文件47│ └── specs/ # Feature specifications / 功能规范48├── .skill_cortex_cache/ # Cache directory / 缓存目录49│ └── index.json # Skill index cache / 技能索引缓存50├── .skill_cortex_sources/ # Imported skills source / 导入的技能源51├── .skills/ # Local skills directory / 本地技能目录52│ └── imported/ # Imported skills / 导入的技能53├── import_skills.py # Enhanced skill import script / 增强的技能导入脚本54├── pyproject.toml # Project configuration / 项目配置55├── README.md # This file / 本文件56└── tags.md # Allowed tags list / 允许的标签列表57```5859## Quick Start / 快速开始6061### Installation / 安装6263```bash64# Install in editable mode / 以可编辑模式安装65pip install -e .6667# Or install from PyPI (when available) / 或从 PyPI 安装（当可用时）68pip install skill-cortex-lite69```7071### Run the Server / 运行服务器7273```bash74# Run directly / 直接运行75skill-cortex7677# Or use Python module / 或使用 Python 模块78python -m skill_cortex.server79```8081## MCP Tools / MCP 工具8283### 1. list_skill_tree / 列出技能树8485Browse skills in a hierarchical tree structure / 以分层树结构浏览技能8687**Parameters / 参数:**88- `path` (optional): Starting path in the skill tree / 技能树中的起始路径8990**Example / 示例:**91```json92{93 "path": "coding"94}95```9697**Response / 响应:**98Returns a hierarchical tree of skills with their metadata / 返回包含元数据的分层技能树99100### 2. search_skills / 搜索技能101102Search for skills by query text / 通过查询文本搜索技能103104**Parameters / 参数:**105- `query` (optional): Search query string / 搜索查询字符串106- `tags` (optional): Array of tags to filter by / 用于筛选的标签数组107108**Example / 示例:**109```json110{111 "query": "database",112 "tags": ["coding", "data"]113}114```115116**Response / 响应:**117Returns matching skills with their details / 返回匹配的技能及其详细信息118119### 3. get_skill_details / 获取技能详情120121Get detailed information about a specific skill with context compression / 获取特定技能的详细信息，支持上下文压缩122123**Parameters / 参数:**124- `skill_id` (required): Unique identifier of the skill / 技能的唯一标识符125- `section` (optional): What to return / 返回内容类型126 - `"summary"` (default): Frontmatter + description snapshot (token-friendly) / 仅元数据和描述摘要（节省token）127 - `"instructions"`: Main instructions section only / 仅主要指令部分128 - `"examples"`: Code examples section only / 仅代码示例部分129 - `"full"`: Complete SKILL.md content / 完整内容130- `max_lines` (optional): Limit output to N lines / 限制输出行数131132**Example / 示例:**133```json134{135 "skill_id": "coding/database/query",136 "section": "summary"137}138```139140```json141{142 "skill_id": "coding/database/query",143 "section": "instructions",144 "max_lines": 50145}146```147148**Response / 响应:**149Returns skill information based on section parameter / 根据 section 参数返回技能信息150151### 4. update_tags / 更新标签152153Manage tags inside skills frontmatter / 管理 skills 的 frontmatter tags154155**Parameters / 参数:**156- `mode` (required): "list" or "apply" / 操作模式："list" 或 "apply"157- `updates` (optional): required when mode is "apply" / 当 mode 为 "apply" 时需要提供158159**Example / 示例:**160```json161{162 "mode": "list"163}164```165166```json167{168 "mode": "apply",169 "updates": [170 {"skill_id": "...", "tags": ["python", "mcp"]}171 ]172}173```174175**Response / 响应:**176Returns the current tags list or operation result / 返回当前标签列表或操作结果177178### 5. create_new_skill / 创建新技能179180Create a new skill with automatic validation and indexing / 创建新技能并自动验证和索引181182**Parameters / 参数:**183- `path` (required): Skill path (e.g., "coding/python-helper" or "simple-skill") / 技能路径184- `description` (required): Skill description (1-1024 characters) / 技能描述（1-1024字符）185- `tags` (optional): Array of tags / 标签数组186- `instructions` (optional): Custom instructions (if not provided, a template will be generated) / 自定义指令（如未提供则生成模板）187- `license` (optional): License information / 许可证信息188- `metadata` (optional): Metadata dict (e.g., {"author": "example", "version": "1.0"}) / 元数据字典189- `create_scripts_dir` (optional): Whether to create scripts/ directory / 是否创建 scripts/ 目录190- `create_references_dir` (optional): Whether to create references/ directory / 是否创建 references/ 目录191- `create_assets_dir` (optional): Whether to create assets/ directory / 是否创建 assets/ 目录192193**Example / 示例:**194```json195{196 "path": "coding/python-helper",197 "description": "A helper skill for Python development tasks",198 "tags": ["python", "coding", "development"],199 "create_scripts_dir": true200}201```202203```json204{205 "path": "simple-skill",206 "description": "A simple skill example",207 "tags": ["example"],208 "instructions": "## Instructions\n\nDetailed instructions here...",209 "metadata": {"author": "example-user", "version": "1.0"}210}211```212213**Response / 响应:**214Returns creation result with skill path and details / 返回创建结果，包含技能路径和详细信息215216**Notes / 注意事项:**217- Skills are created in the `.skills/` directory / 技能创建在 `.skills/` 目录中218- Skill names must be lowercase with hyphens only / 技能名称必须是小写字母和连字符219- Supports category paths (e.g., "coding/python-helper") / 支持分类路径220- Automatically validates name format and updates index / 自动验证名称格式并更新索引221222### 6. delete_existing_skill / 删除现有技能223224Delete a user-created skill (requires confirmation) / 删除用户创建的技能（需要确认）225226**Parameters / 参数:**227- `skill_id` (required): Unique identifier of the skill to delete / 要删除的技能的唯一标识符228- `confirm` (required): Must be True to actually delete (False shows preview only) / 必须为 True 才能实际删除（False 仅显示预览）229230**Example / 示例:**231```json232{233 "skill_id": ".skills:coding/python-helper/SKILL.md",234 "confirm": false235}236```237238```json239{240 "skill_id": ".skills:simple-skill/SKILL.md",241 "confirm": true242}243```244245**Response / 响应:**246Returns deletion result or preview information / 返回删除结果或预览信息247248**Safety Features / 安全特性:**249- Only allows deletion of skills in `.skills/` directory / 仅允许删除 `.skills/` 目录中的技能250- Cannot delete imported skills (`.skills/imported/`) / 无法删除导入的技能251- Cannot delete source repository skills (`.skill_cortex_sources/`) / 无法删除源仓库技能252- Requires explicit `confirm=true` to execute deletion / 需要显式 `confirm=true` 才能执行删除253- Automatically updates index after deletion / 删除后自动更新索引254255## Configuration / 配置256257### Environment Variables / 环境变量258259- `SKILL_CORTEX_ROOTS`: Comma-separated list of skill root directories / 逗号分隔的技能根目录列表260 - Default: `~/.claude/skills,./.skills` / 默认值261 - Example: `/path/to/skills1,/path/to/skills2` / 示例262263- `SKILL_CORTEX_CACHE_PATH`: Path to the index cache file / 索引缓存文件路径264 - Default: `./.skill_cortex_cache/index.json` / 默认值265 - Example: `/custom/path/cache.json` / 示例266267- `SKILL_CORTEX_TAGS_PATH`: Path to the allowed tags file / 允许的标签文件路径268 - Default: `./tags.md` / 默认值269 - Example: `/custom/path/tags.md` / 示例270271### Example Configuration / 配置示例272273```json274{275 "mcpServers": {276 "skill-cortex-lite": {277 "command": "skill-cortex",278 "args": [],279 "env": {280 "SKILL_CORTEX_ROOTS": "/Users/username/skills1,/Users/username/skills2",281 "SKILL_CORTEX_CACHE_PATH": "/Users/username/.skill_cortex_cache/index.json",282 "SKILL_CORTEX_TAGS_PATH": "/Users/username/tags.md"283 }284 }285 }286}287```288289## Importing Skills / 导入技能290291The project includes an enhanced import script with advanced features for importing skills from public repositories / 项目包含一个增强的导入脚本，具有从公共仓库导入技能的高级功能292293### Enhanced Import Features / 增强导入功能294295#### 🔧 Configuration File Support / 配置文件支持296- **YAML/JSON Configuration**: Use configuration files to customize repository lists without modifying code / 使用配置文件自定义仓库列表，无需修改代码297- **Auto-discovery**: Automatically finds `skills-config.yaml`, `skills-config.yml`, or `skills-config.json` in current directory / 自动查找当前目录中的配置文件298- **Custom config path**: Use `--config` option to specify custom configuration file / 使用 `--config` 选项指定自定义配置文件299300#### 📊 Progress Display / 进度显示301- **Real-time progress**: Shows current repository being processed with step-by-step feedback / 显示当前处理的仓库和逐步反馈302- **Skill counting**: Displays number of skills found in each repository / 显示每个仓库中找到的技能数量303- **Comprehensive summary**: Final report with statistics, timing, and success/failure counts / 包含统计、时间和成功/失败计数的最终报告304305#### 🛡️ Robust Error Handling / 健壮错误处理306- **Continue on error**: Single repository failure doesn't stop the entire import process / 单个仓库失败不会停止整个导入过程307- **Detailed error reporting**: Clear error messages with specific failure reasons / 清晰的错误消息和具体失败原因308- **Error categorization**: Different handling for network, file system, and Git errors / 对网络、文件系统和Git错误的不同处理309310#### 🔍 Enhanced Preview Mode / 增强预览模式311- **Detailed dry-run**: Shows repository URLs, skill paths, and counts before actual import / 在实际导入前显示仓库URL、技能路径和计数312- **Clear indicators**: Clearly shows when running in preview mode with no actual changes / 清楚显示预览模式，不进行实际更改313314### Built-in Skills / 内置技能315316This repository does not bundle skills by default. Use the import script (optional) to fetch skills from public repositories / 本仓库默认不内置 skills，可使用导入脚本（可选）从公共仓库拉取：317318#### 1. [agentskills/agentskills](https://github.com/agentskills/agentskills)319320A comprehensive collection of AI agent skills and capabilities / 一个全面的 AI 代理技能和能力集合321322- **Features / 特性**: Provides a wide range of skills for AI agents, including coding, data analysis, and problem-solving / 为 AI 代理提供广泛的技能，包括编码、数据分析和问题解决323- **Skill Types / 技能类型**: Coding, debugging, testing, optimization, and more / 编码、调试、测试、优化等324- **Usage / 用途**: Enhances AI agent capabilities with practical, reusable skills / 通过实用的、可重用的技能增强 AI 代理能力325326#### 2. [anthropics/skills](https://github.com/anthropics/skills)327328Official skills repository from Anthropic / Anthropic 的官方技能仓库329330- **Features / 特性**: Officially maintained skills optimized for Claude AI / 官方维护的针对 Claude AI 优化的技能331- **Skill Types / 技能类型**: Documentation, code generation, system administration, and more / 文档、代码生成、系统管理等332- **Usage / 用途**: Provides high-quality, tested skills for production use / 为生产环境提供高质量、经过测试的技能333334#### 3. [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills)335336Community-curated collection of Claude Skills resources / 社区策划的Claude Skills资源集合337338- **Features / 特性**: Curated list of awesome Claude Skills, resources, and tools / 精选的Claude Skills、资源和工具列表339- **Skill Types / 技能类型**: Various community-contributed skills and resources / 各种社区贡献的技能和资源340- **Usage / 用途**: Access to community-driven skill collections / 访问社区驱动的技能集合341342#### 4. [huggingface/skills](https://github.com/huggingface/skills)343344Hugging Face's skills repository for AI and machine learning / Hugging Face 的 AI 和机器学习技能仓库345346- **Features / 特性**: Skills and tools for working with Hugging Face ecosystem / 用于 Hugging Face 生态系统的技能和工具347- **Skill Types / 技能类型**: Machine learning, model training, dataset handling, and more / 机器学习、模型训练、数据处理等348- **Usage / 用途**: Enhances capabilities for AI/ML tasks and Hugging Face integrations / 增强 AI/ML 任务和 Hugging Face 集成的能力349350### Import Script Usage / 导入脚本使用351352#### Basic Usage / 基本使用353354```bash355# Preview what would be imported (recommended first step) / 预览将要导入的内容（推荐第一步）356python import_skills.py --dry-run357358# Actually import the skills / 实际导入技能359python import_skills.py360361# Clean import (remove existing skills first) / 清理导入（先删除现有技能）362python import_skills.py --clean363```364365#### Advanced Usage / 高级使用366367```bash368# Use custom configuration file / 使用自定义配置文件369python import_skills.py --config my-config.yaml370371# Import only specific repositories / 仅导入特定仓库372python import_skills.py --only anthropics_skills --only agentskills_agentskills373374# Skip cloning (use existing local repositories) / 跳过克隆（使用现有本地仓库）375python import_skills.py --no-clone376377# Don't update existing repositories / 不更新现有仓库378python import_skills.py --no-update379```380381#### Configuration File Examples / 配置文件示例382383**YAML Configuration (skills-config.yaml):**384```yaml385repositories:386 - name: "anthropics_skills"387 url: "https://github.com/anthropics/skills.git"388 enabled: true389390 - name: "agentskills_agentskills"391 url: "https://github.com/agentskills/agentskills.git"392 enabled: true393394 - name: "composio_awesome_skills"395 url: "https://github.com/ComposioHQ/awesome-claude-skills.git"396 enabled: true397398 - name: "huggingface_skills"399 url: "https://github.com/huggingface/skills.git"400 enabled: true401402settings:403 incremental: false404 validation: false405```406407**JSON Configuration (skills-config.json):**408```json409{410 "repositories": [411 {412 "name": "anthropics_skills",413 "url": "https://github.com/anthropics/skills.git",414 "enabled": true415 },416 {417 "name": "agentskills_agentskills",418 "url": "https://github.com/agentskills/agentskills.git",419 "enabled": true420 },421 {422 "name": "composio_awesome_skills",423 "url": "https://github.com/ComposioHQ/awesome-claude-skills.git",424 "enabled": true425 },426 {427 "name": "huggingface_skills",428 "url": "https://github.com/huggingface/skills.git",429 "enabled": true430 }431 ],432 "settings": {433 "incremental": false,434 "validation": false435 }436}437```438439### Import Process / 导入过程440441Skills are imported to: `./.skill_cortex_sources/` / 技能导入到：`./.skill_cortex_sources/`442443Skills are copied to: `./.skills/imported/` / 技能拷贝到：`./.skills/imported/`444445The import process includes:4461. **Repository cloning/updating** / 仓库克隆/更新4472. **Skill discovery** / 技能发现4483. **File copying** / 文件复制4494. **Progress reporting** / 进度报告4505. **Error handling** / 错误处理451452## Troubleshooting / 故障排除453454### ModuleNotFoundError / 模块未找到错误455456**Problem / 问题:**457```458ModuleNotFoundError: No module named 'skill_cortex'459```460461**Solution / 解决方案:**462Install the package in editable mode / 以可编辑模式安装包463```bash464pip install -e .465```466467### Skills not appearing / 技能未显示468469**Problem / 问题:**470Skills are not showing up in the tool results / 技能未在工具结果中显示471472**Solution / 解决方案:**4731. Check that `SKILL_CORTEX_ROOTS` points to correct directories / 检查 `SKILL_CORTEX_ROOTS` 是否指向正确的目录4742. Verify that `SKILL.md` files exist in those directories / 验证这些目录中是否存在 `SKILL.md` 文件4753. Clear the cache by deleting the index.json file / 通过删除 index.json 文件清除缓存4764. Restart the server / 重启服务器477478### Tag validation errors / 标签验证错误479480**Problem / 问题:**481Tags are being rejected / 标签被拒绝482483**Solution / 解决方案:**4841. Check the `tags.md` file for the allowed tags list / 检查 `tags.md` 文件中的允许标签列表4852. Use the `update_tags` tool to add missing tags / 使用 `update_tags` 工具添加缺失的标签4863. Ensure tag names match exactly (case-sensitive) / 确保标签名称完全匹配（区分大小写）487488### Import script errors / 导入脚本错误489490**Problem / 问题:**491Import script fails with configuration or repository errors / 导入脚本因配置或仓库错误而失败492493**Solution / 解决方案:**4941. Use `--dry-run` first to preview what will be imported / 首先使用 `--dry-run` 预览将要导入的内容4952. Check configuration file syntax if using custom config / 如果使用自定义配置，检查配置文件语法4963. Verify repository URLs are accessible / 验证仓库URL是否可访问4974. Use `--no-clone` to skip cloning if repositories already exist locally / 如果仓库已存在本地，使用 `--no-clone` 跳过克隆4985. Check the detailed error report in the final summary / 检查最终摘要中的详细错误报告499500## Development / 开发501502### Project Setup / 项目设置503504```bash505# Clone the repository / 克隆仓库506git clone <repository-url>507cd skill_cortex_server508509# Install in development mode / 以开发模式安装510pip install -e .511```512513### Running Tests / 运行测试514515```bash516# Run all tests / 运行所有测试517pytest518519# Run with coverage / 运行并生成覆盖率报告520pytest --cov=skill_cortex521```522523## Contributing / 贡献524525Contributions are welcome! Please feel free to submit a Pull Request / 欢迎贡献！请随时提交 Pull Request5265271. Fork the repository / Fork 仓库5282. Create your feature branch / 创建功能分支5293. Commit your changes / 提交更改5304. Push to the branch / 推送到分支5315. Open a Pull Request / 打开 Pull Request532533## License / 许可证534535This project is licensed under the MIT License / 本项目采用 MIT 许可证536537## Acknowledgments / 致谢538539- Inspired by Claude Code Skills / 灵感来自 Claude Code Skills540- Built with MCP (Model Context Protocol) / 使用 MCP（模型上下文协议）构建541- Reference implementation based on mcp-sequential-thinking / 基于 mcp-sequential-thinking 的参考实现542543## Contact / 联系方式544545For questions and support, please open an issue on GitHub / 如有问题和支持需求，请在 GitHub 上提交 issue546
Full transparency — inspect the skill content before installing.