AI Skills Hub

An MCP (Model Context Protocol) server that dynamically loads Markdown skill files, enabling AI assistants to access your team's coding standards, best practices, and skill knowledge base.

Languages / 語言

- English
- 繁體中文

Project Architecture

``
ai-skills-hub/
├── src/ # --- MCP Server Core (Librarian) ---
│ ├── index.ts # Auto-scans ~/.ai-skills-hub/skills/*/SKILL.md and converts to MCP Tools
│ ├── cli.ts # CLI tool entry point
│ ├── utils.ts # Helper functions (Markdown parsing, path handling)
│ └── commands/ # CLI command implementations
│ ├── sync.ts # Sync command
│ └── check.ts # Check command
├── dist/ # [Ignore] Compiled JS (actual execution code)
├── package.json # Project dependencies and script definitions
├── tsconfig.json # TypeScript configuration
└── README.md # Team usage manual
`

Installation

$3

Install the package globally to use the CLI commands from anywhere:

`bash
npm install -g ai-skills-hub
`

After installation, you can use both skillshub and ai-skills-hub commands:

`bash


Sync skills library and configure AI tools

skillshub sync

Or use the full command name

ai-skills-hub sync

Add a skill from URL

skillshub add

Check status

skillshub check

List all skills

skillshub list

View help

skillshub help
`

$3

If you prefer not to install globally, you can use npx to run commands directly:

`bash


Sync skills library and configure AI tools

npx ai-skills-hub sync

Add a skill from URL

npx ai-skills-hub add

Check status

npx ai-skills-hub check

List all skills

npx ai-skills-hub list

View help

npx ai-skills-hub help
`

$3

For contributing or local development:

1. Clone the project
`bash
git clone
cd ai-skills-hub
`

2. Install dependencies
`bash
npm install
`

3. Build the project
`bash
npm run build
`

4. Link for local development
`bash
npm link
`

After linking, you can use skillshub commands as if it were globally installed.

CLI Commands

$3

Sync and update AI tool configurations. This command will:
- Compile TypeScript code (in local development mode)
- Configure MCP settings for supported AI tools

Note: Skills are stored in ~/.ai-skills-hub/skills/, not in the repository. Use skillshub add to add skills from a repository.

Options:
- -f, --force: Force recompilation even if there are no changes

Examples:
`bash
skillshub sync
skillshub sync --force
`

$3

Check AI tool installation status and MCP configuration status.

This command will:
- Display which AI tools are currently installed
- Display which AI tools have MCP routes configured
- Provide a configuration status summary

Options:
- -v, --verbose: Show detailed information (version numbers, config file paths, commands, etc.)

Examples:
`bash
skillshub check
skillshub check --verbose
`

Output Legend:
- ✓ Green marker: Installed/Configured
- ○ Yellow marker: Not installed/Not configured

$3

Add a skill from a URL to your local skills library.

This command will:
- Download a SKILL.md file from the provided URL
- Automatically convert GitHub blob URLs to raw URLs
- Extract the skill name from the URL path
- Save the skill to ~/.ai-skills-hub/skills//

Options:
- -f, --force: Overwrite existing skill if it already exists

Examples:
`bash


Add a skill from GitHub blob URL

skillshub add https://github.com/user/repo/blob/main/skills/api-design/SKILL.md

Add a skill from raw URL

skillshub add https://raw.githubusercontent.com/user/repo/main/skills/api-design/SKILL.md

Force overwrite existing skill

skillshub add https://github.com/user/repo/blob/main/skills/api-design/SKILL.md --force
`

URL Formats:
- GitHub blob URL: https://github.com/{user}/{repo}/blob/{branch}/path/to/SKILL.md
- Raw GitHub URL: https://raw.githubusercontent.com/{user}/{repo}/{branch}/path/to/SKILL.md
- The command automatically converts blob URLs to raw URLs

Workflow:
1. Command downloads the SKILL.md file from the URL
2. Extracts skill name from the directory path (e.g., api-design from .../api-design/SKILL.md)
3. Creates directory ~/.ai-skills-hub/skills//
4. Saves the file as SKILL.md in that directory
5. Run skillshub sync to update MCP configuration

$3

List all available skills and their descriptions.

This command will:
- Scan all SKILL.md files in the ~/.ai-skills-hub/skills/ directory
- Display each skill's filename, tool name, and description
- Provide usage tips

Options:
- -v, --verbose: Show detailed information (file size, line count, last modified time)

Examples:
`bash
skillshub list
skillshub list --verbose
`

Output Content:
- Filename (e.g., api-design.md)
- Tool name (e.g., api_design)
- Description (extracted from the first heading in the Markdown file)
- Detailed information (verbose mode): file size, line count, modification time

$3

Display help information.

Supported AI Tools

This project supports MCP configuration for the following AI tools:

- Claude Desktop - Anthropic's Claude desktop application
- Cursor - AI-powered code editor
- OpenAI Codex - OpenAI's code assistant CLI
- GitHub Copilot CLI - GitHub's AI code assistant
- Gemini CLI - Google's Gemini AI CLI tool
- Claude Code CLI - Anthropic's Claude Code command-line tool

$3

#### OpenAI Codex CLI
`bash
npm install -g @openai/codex


Set environment variable


export OPENAI_API_KEY="your-api-key"
`

#### GitHub Copilot CLI
`bash


macOS/Linux (using Homebrew)

brew install copilot-cli

Or using npm

npm install -g @github/copilot-cli
`

#### Gemini CLI
`bash
npm install -g @google/gemini-cli


Login or set API key

gemini auth login

Or

export GEMINI_API_KEY="your-api-key"
`

#### Claude Code CLI
`bash
npm install -g @anthropic-ai/claude-code


Set environment variable


export ANTHROPIC_API_KEY="your-api-key"
`

Usage

$3

Skills are stored locally in ~/.ai-skills-hub/skills/. To add a skill:

1. Manual Method: Create a directory in ~/.ai-skills-hub/skills/ (e.g., api-design/) and add a SKILL.md file inside it
2. Using CLI: Use skillshub add to add skills from a Git repository
3. The directory name will be automatically converted to a tool name (e.g., api-design/ → api_design)

$3

Skill files use standard Markdown format:

`markdown


Skill Title

This is the skill description...

Section

Content...

$3

More content...
`

- The first heading will automatically be used as the tool description
- Supports all standard Markdown syntax (headings, lists, code blocks, etc.)

$3

Skills can include executable scripts (shell scripts, Python scripts, etc.) that AI agents can run using standard Shell tools.

Directory Structure:
`
~/.ai-skills-hub/skills/
└── your-skill/
├── SKILL.md
├── scripts/
│ ├── setup.sh
│ ├── test.py
│ └── validate.sh
└── resources/
`

Execution Context:

When AI calls a skill tool, it automatically receives execution context information:
- Skill Name: The name of the skill
- Skill Directory: The absolute path to the skill directory (e.g., /Users/username/.ai-skills-hub/skills/your-skill)
- Usage Instructions: Guidance to use the Shell tool with the provided working directory

How to Guide AI to Execute Scripts in SKILL.md:
`markdown


My Skill

When working with this skill, follow these steps:

Setup

Run the setup script to prepare the environment:
`bash
bash scripts/setup.sh
`

Testing

Validate the implementation using:
`bash
bash scripts/test.sh --verbose
`

Or use the Python validation script:
`bash
python3 scripts/validate.py
`

Available Scripts

- setup.sh - Prepares the development environment
- test.sh - Runs unit tests with coverage reporting
- validate.py - Validates code quality and standards

...
`

How It Works:

1. AI receives the skill content with execution context
2. AI sees the script paths and commands in SKILL.md
3. AI uses the Shell tool with working_directory set to the skill directory
4. Scripts execute in the correct directory context automatically




$3

Important: MCP tools are only available in Cursor's Agent mode!

1. Configure MCP (if not already configured):
`bash
skillshub sync
`

2. Restart Cursor to load the new MCP configuration

3. Enable Agent Mode:
- Open Cursor chat panel (Cmd+L or Ctrl+L)
- Switch to Agent mode (not Chat mode)

4. Use Skills:
In Agent mode, ask in natural language, for example:
`
Please use api_design to help me design a RESTful API
`
`
According to go_concurrency standards, help me refactor this code
`

$3

`bash


Start the server (using stdio transport)


npm start
`

The server will communicate with MCP clients through standard input/output.

Core Components

🏗️ Core Components

1. ~/.ai-skills-hub/skills/*/SKILL.md (Skill Definitions)
Skills are stored locally in each user's home directory. Each skill is a directory containing a SKILL.md file.

Advantages: Engineers only need to write in Markdown: "When I need to do task X, please follow steps Y, examples below...", and the AI will understand.

Maintenance: Anyone who can write Markdown can add or modify skills. Skills can be managed individually or synced from shared repositories.

2. src/index.ts (Dynamic Loader)
This MCP Server no longer contains specific business logic. It only does two things:

- List tools (list_tools): Scans the ~/.ai-skills-hub/skills/ directory and converts each skill directory into a tool name for the AI (e.g., api-design/ → api_design).

- Pass content with context (call_tool): When the AI requests it, reads the corresponding SKILL.md content from ~/.ai-skills-hub/skills/ and provides it to the AI along with execution context information (skill name, absolute directory path, and usage instructions for executing scripts).

3. CLI Tool (skillshub)
This CLI tool helps manage skills and AI tool configurations:

- Use skillshub add to add skills from Git repositories to ~/.ai-skills-hub/skills/
- Run skillshub sync to compile TypeScript code and configure MCP settings for AI tools
- Automatically configures global settings for all supported AI tools (Claude Desktop, Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, Claude Code CLI)

🔄 Team Collaboration Workflow

- Skill Repository: Team maintains skill repositories (e.g., on GitHub) with standardized skill definitions.

- Add Skills: Team member A adds a skill repository using skillshub add , which clones it to ~/.ai-skills-hub/skills/.

- Skill Updates: When the skill repository is updated, team members can update their local copy or re-add the skill.

- AI Ready: Team member B opens Cursor or Claude and asks: "Help me write a new Service logic", and the AI will actively read and adopt the skills from ~/.ai-skills-hub/skills/.

🌟 Why This is Suitable for a Team with 30 Microservices?

- No Pollution: The source code of these 30 projects doesn't need any changes. No need to put .cursorrules or .claudeprompt in each project.

- Centralized: There's only one copy of the standards. If you put a copy in each of the 30 projects, updating them would be a disaster.

- Cross-AI Tools: Whether team members prefer Cursor, Claude Desktop, Codex, Copilot, Gemini, or Claude Code CLI, as long as they connect to this MCP, they all read the same "team brain".

Development Guide

$3

- npm run build - Compile TypeScript to dist/ directory
- npm start - Run the compiled MCP server
- npm run dev - Watch mode compilation (for development)

$3

If you want team members to be able to use the npx ai-skills-hub command, you need to publish the package to npm first.

📖 Detailed Guide: Please refer to NPM_PUBLISH_SOP.md for the complete publishing standard operating procedure.

Quick Publishing Steps:

1. Login to npm
`bash
npm login
`

2. Verify package name is available
`bash
npm view ai-skills-hub
`
If the package name is already taken, you need to modify the name field in package.json.

3. Publish the package
`bash
npm publish
`

Note: The prepublishOnly script will automatically run npm run build to ensure the latest code is compiled before publishing.

4. Verify publication
`bash
npx ai-skills-hub --version
`

After publishing, team members can use Method 1 (npx) to install and use this tool.

$3

- src/index.ts - MCP server main program, implements list_tools and call_tool handlers
- src/cli.ts - CLI tool entry point
- src/utils.ts - Utility functions: directory scanning, filename conversion, file reading, etc.
- src/commands/ - CLI command implementations (sync, check, add, list, etc.)
- ~/.ai-skills-hub/skills/ - Local directory for storing skill Markdown files (created on first use)

$3

For Project Development:
1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes to the MCP server or CLI tool
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

For Adding Skills:
Skills are managed separately in their own repositories. Users add skills using skillshub add . To create a new skill repository, see the skill repository documentation.

$3

#### AI Tool Can't Connect to MCP Server

- Confirm you've run skillshub sync to update configuration
- Check if the configuration file path is correct
- Some tools may need to be restarted to load new configuration
- Verify the MCP server path is correct in the configuration file
- Use skillshub check` to check configuration status

License

MIT License