Skip to content

aialt/fastskills

BranchesTags

Repository files navigation

FastSkills

中文 | English

An open-source, community-driven Agent framework that supports Claude's new Skills.

Project Purpose

FastSkills provides a low-level interface layer that bridges LLM APIs or inference services to Skills tool invocation. The upper layer supports integration with any form of agent system.

FastSkills aims to provide developers with:

  • Low-Level Protocol Layer: Bridge between LLM APIs/inference services and Skills tool invocation protocol
  • Agent System Agnostic: Upper layer supports integration with any form of agent system
  • Agent Skills Integration: Support for the Agent Skills open standard. Skills are folders containing instructions, scripts, and resources that are dynamically loaded through progressive disclosure, providing specialized procedural knowledge for agents
  • Community-Driven: Open-source and transparent, maintained and developed by the community
  • Easy to Use: Simple APIs and clear documentation to lower the barrier to entry

Core Features

  • 🔌 Agent Skills Support: Native support for Agent Skills open standard, including SKILL.md parsing, progressive disclosure loading, and code execution
  • 🚀 High Performance: Optimized architecture design for fast response
  • 📦 Modular: Flexible module design, easy to extend and customize
  • 🌐 Open Source: Community-driven, contributions welcome
  • 🔧 MCP Server: Model Context Protocol server for discovering and managing skills

Demo

Langchain use case

FastSkills LangChain Demo

About Skills

Skills (Procedural Knowledge)

Skills provide procedural knowledge—instructions for how to complete specific tasks or workflows. Skills are folders containing a SKILL.md file and can include:

  • Instructions and documentation: Guidance in Markdown format
  • Executable code: Scripts in Python, JavaScript, etc., that agents can execute as needed
  • Resource files: Additional files needed to support tasks

Skills work through progressive disclosure: Agents first load metadata (name and description) for all Skills, then dynamically load full Skill content based on task relevance.

Skills vs. Other Concepts

  • Skills vs. Projects: Projects provide static background knowledge that's always loaded within projects; Skills provide dynamically activated specialized procedures that work everywhere
  • Skills vs. Custom Instructions: Custom Instructions apply broadly to all conversations; Skills are task-specific and only load when relevant

Current Status

Status: MCP Server Implementation Available

This repository provides an MCP (Model Context Protocol) server for discovering and managing skills. The server includes:

  • Skill discovery and reading tools
  • Filesystem operations for skill management
  • Code sandbox for safe Python code execution
  • Support for .claude/skills directory structure

Installation

Python Dependencies

Recommended: Using uv (Fast Python Package Installer)

uv is a fast Python package installer and resolver written in Rust. It's significantly faster than pip and provides better dependency resolution.

Install uv:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

Install FastSkills with uv:

# Install the project and all dependencies (recommended)
uv sync

# Or install with optional dependencies for examples
uv sync --extra examples

# uv sync automatically creates and manages the virtual environment
# To activate it manually:
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Benefits of using uv:

  • ⚡ 10-100x faster than pip
  • 🔒 Better dependency resolution and conflict detection
  • 📦 Automatic virtual environment management - no need to manually create/activate venv
  • 🚀 uv run - automatically uses project's virtual environment
  • 🔄 Compatible with pip - can use uv pip as a drop-in replacement

Alternative: Using pip

If you prefer using pip:

pip install .

System Dependencies

LibreOffice is required for certain skills (e.g., the xlsx skill) that need to recalculate Excel formulas. This is a requirement from .claude/skills specifications.

macOS:

brew install --cask libreoffice

Linux:

# Ubuntu/Debian
sudo apt-get install libreoffice

# Fedora/RHEL
sudo dnf install libreoffice

Windows: Download and install from LibreOffice website.

After installation, ensure the soffice command is available in your PATH. You can verify this by running:

soffice --version

Setting PATH Environment Variable:

If soffice is not found in your PATH (common on macOS), you need to add LibreOffice to your PATH:

macOS:

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
export PATH="/Applications/LibreOffice.app/Contents/MacOS:$PATH"

# Or set it for the current session
export PATH="/Applications/LibreOffice.app/Contents/MacOS:$PATH"

Linux:

# Usually already in PATH after installation, but if needed:
export PATH="/usr/bin:$PATH"
# Or for custom installations:
export PATH="/opt/libreoffice*/program:$PATH"

For Virtual Environments:

When using a virtual environment, you may need to set the PATH before executing code that uses LibreOffice:

With uv:

# uv automatically manages virtual environments
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
export PATH="/Applications/LibreOffice.app/Contents/MacOS:$PATH"
python your_script.py

With pip:

source .venv/bin/activate
export PATH="/Applications/LibreOffice.app/Contents/MacOS:$PATH"
python your_script.py

For MCP Server:

If running the MCP server and using skills that require LibreOffice, add the PATH to your MCP client configuration:

{
  "mcpServers": {
    "fastskills": {
      "command": "python",
      "args": ["-m", "fastskills.mcp_server"],
      "env": {
        "FASTSKILLS_TOP_K": "5",
        "PATH": "/Applications/LibreOffice.app/Contents/MacOS:${PATH}"
      }
    }
  }
}

MCP Server Usage

Running the MCP Server

Using uv (Recommended):

# Standard stdio mode (for MCP clients)
uv run python -m fastskills.mcp_server

# HTTP mode (for testing with Inspector)
uv run python -m fastskills.mcp_server --transport sse --port 8000

Using pip or activated virtual environment:

# Standard stdio mode (for MCP clients)
python -m fastskills.mcp_server

# HTTP mode (for testing with Inspector)
python -m fastskills.mcp_server --transport sse --port 8000

Configuration

Environment Variables

  • FASTSKILLS_TOP_K: Number of top results to return from search_skill (default: 15)

  • FS_BASE_DIRECTORY: Base directory to restrict all filesystem operations to (security feature, optional)

  • CODE_SANDBOX_MODULES: Comma-separated list of allowed Python modules for code execution (default: "pandas,openpyxl,pathlib,os,sys,json,datetime,time")

    Note: High-privilege modules like subprocess are intentionally excluded from the default allowlist for security. They can be enabled explicitly via the CODE_SANDBOX_MODULES environment variable if required.

export FASTSKILLS_TOP_K=10
export FS_BASE_DIRECTORY="./workspace"  # Restrict filesystem access
export CODE_SANDBOX_MODULES="pandas,openpyxl,pathlib,os"
python -m fastskills.mcp_server

MCP Client Configuration

For Claude Desktop, add to your MCP configuration file (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "fastskills": {
      "command": "python",
      "args": ["-m", "fastskills.mcp_server"],
      "env": {
        "FASTSKILLS_TOP_K": "15"
      }
    }
  }
}

Available Tools

The MCP server provides tools in three categories:

1. Skills Tools

read_skill

Read a specific skill by name, returning the full content of the skill's SKILL.md file, plus information about any Python scripts available in the skill directory.

Parameters:

  • skill_name (string, required): The name of the skill to read

Returns: Full content of the skill's SKILL.md file with script paths appended

search_skill

Search for skills by description. Returns top-k matching skills (k is configurable via FASTSKILLS_TOP_K environment variable, default: 15).

Parameters:

  • query (string, required): Search query describing the skill you're looking for

Returns: List of top-k matching skills with names and descriptions

2. Filesystem Tools

  • read_file - Read a file from the filesystem
  • write_file - Write content to a file (creates file and parent directories if needed)
  • update_file - Perform targeted search-and-replace operations within a file (supports regex)
  • list_files - List files and directories (supports recursive listing)
  • delete_file - Delete a file
  • delete_directory - Delete a directory (with optional recursive deletion)
  • create_directory - Create a new directory
  • move_path - Move or rename a file or directory
  • copy_path - Copy a file or directory
  • set_filesystem_default - Set a default directory for resolving relative paths

3. Code Sandbox Tools

execute_python_code

Execute Python code safely in a sandbox environment (for creating Excel files, data processing, etc.).

Parameters:

  • code (string, required): Python code to execute

Returns: Execution result with output, errors, or results

Note: Code is executed in the project root directory to ensure access to project files. Only modules specified in CODE_SANDBOX_MODULES are available.

Skill Discovery

The server automatically discovers skills from:

  • ~/.claude/skills/ directory
  • Current working directory

Skills are directories containing a SKILL.md file with YAML frontmatter:

---
name: my_skill
description: A skill that does something useful
---

# My Skill

Skill content here...

Examples

See the examples/ directory for usage examples:

  • langchain_mcp_example.py - Example of using FastSkills MCP server with LangChain agent

Using uv (Recommended):

# Install with example dependencies
uv sync --extra examples

# Run the example (uv automatically uses the project's virtual environment)
export OPENAI_API_KEY="your-api-key"
uv run python examples/langchain_mcp_example.py

Using pip:

# Install example dependencies
pip install langchain langchain-openai langchain-core langchain-mcp-adapters

# Run the example
export OPENAI_API_KEY="your-api-key"
python examples/langchain_mcp_example.py

Testing

You can test the server using the MCP Inspector:

npx -y @modelcontextprotocol/inspector

Then connect to your server via stdio transport.

Development Roadmap

Phase 1: Low-Level Interface Layer (In Progress)

Phase 1 provides the foundational interface layer capabilities, including the protocol layer from LLM APIs/inference services to Skills tool invocation. The upper layer supports integration with any form of agent system.

  • Project initialization and foundation architecture setup
  • Protocol layer implementation (LLM APIs/inference services ↔ Skills tool invocation)
  • Interface layer for agent system integration
  • Basic Skills loading and management mechanism
  • MCP Server implementation

Phase 2: Skills System

  • SKILL.md file parsing and YAML frontmatter validation
  • Progressive disclosure mechanism (metadata pre-loading, on-demand full content loading)
  • Skills dynamic loading and context management
  • Skills code execution engine (supporting Python)
  • Skills registration, discovery, and management mechanism
  • More complex code execution engine (supporting Python, JavaScript, etc.)
  • Skills examples and documentation

Phase 3: Advanced Features

  • Agent orchestration and workflow control
  • Multi-Agent collaboration mechanism
  • Context management and persistence
  • Error handling and retry mechanism
  • Performance monitoring and logging system

Phase 4: Tools and Ecosystem

  • CLI tools
  • Web UI interface
  • Plugin system
  • Community Skills marketplace
  • Complete documentation and tutorials

Contributing

Contributions are welcome! You can contribute by opening issues, submitting pull requests, or sharing feedback through the repository's issue tracker.

Development Setup

Prerequisites:

  • Python 3.10 or higher
  • uv package manager (recommended) or pip

Initial Setup:

  1. Fork and clone the repository:

    git clone https://github.com/your-username/fastskills.git
cd fastskills

  2. Install dependencies:

    # Using uv (recommended)
uv sync

# Or using pip
pip install -e .

  3. Install pre-commit hook (required):

    # Install the pre-commit hook using make
make install-hook

  4. Verify installation:

    python -c "import fastskills; print(fastskills.__version__)"

Development Workflow

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes and ensure code quality

  3. Run quality checks (see below)

  4. Commit your changes:

    git add .
git commit -m "feat: description of your changes"

  5. Push and create a Pull Request:

    git push origin feature/your-feature-name

Code Quality Checks

Before submitting a pull request, you must ensure your code passes all quality checks. We use mypy for type checking and ruff for linting and code formatting.

Required checks before submitting a PR:

  1. Type Checking with mypy:

    make mypy

    This will check for type errors across the codebase. If you encounter missing type stubs, run:

    make mypy-fix

    This will automatically install missing type stubs (e.g., types-PyYAML).

  2. Linting and Formatting with ruff:

    make ruff

    This will check code quality and formatting. To automatically fix issues:

    # Safe fixes only (recommended)
make ruff-fix

# Include unsafe fixes (use with caution, review changes carefully)
make ruff-fix-unsafe

  3. Run tests:

    # Using unittest (project's test framework)
python -m unittest discover -s tests -p "test_*.py" -v

Pre-PR Checklist

Before submitting your PR, please ensure:

  • Code Quality:

    • Run make mypy and fix any type errors
    • Run make ruff-fix to fix linting and formatting issues
    • Run make ruff to verify all checks pass
    • All tests pass (python -m unittest discover -s tests -p "test_*.py" -v)

  • Code Standards:

    • Code follows the project's style guidelines
    • No unused imports (checked by ruff)
    • All imports are at the top of files
    • No hard-coded values (use constants)
    • Proper error handling (no generic try-except)

  • Version Management:

    • Version number is updated if code changes were made
    • Used appropriate version increment (patch/minor/major)
    • Version file (fastskills/__version__) is included in the commit
    • Pre-commit hook passes (automatically checks version updates)

  • Documentation:

    • Code is properly commented where necessary
    • README is updated if needed (for user-facing changes)
    • Docstrings are added for new functions/classes

  • Git:

    • Commits follow conventional commit format (e.g., feat:, fix:, docs:)
    • Branch is up to date with the target branch
    • No merge conflicts

CI/CD Workflow

The project includes GitHub Actions workflows that automatically run on every push and pull request:

Quality Checks (runs on all PRs and pushes):

  • ✅ Type Checking - make mypy must pass without errors
  • ✅ Code Linting - make ruff must pass without errors
  • ✅ Code Formatting - Code must be properly formatted (checked by ruff format)
  • ✅ Tests - Test suite runs automatically

Version Management:

  • ⚠️ Version updates are required - All code changes must include a version number update
  • A pre-commit hook automatically checks that version is updated when code changes
  • See Version Management section below for details

Available Make Targets:

make help                      # Show all available targets
make mypy                      # Run type checking
make mypy-fix                  # Install missing type stubs
make ruff                      # Check code quality and formatting
make ruff-fix                  # Auto-fix linting errors (safe fixes)
make ruff-fix-unsafe           # Auto-fix linting errors (including unsafe fixes)
make version                   # Show current version
make patch-version-increment   # Increment patch version
make minor-version-increment   # Increment minor version
make major-version-increment  # Increment major version
make version-set VERSION=x.y.z # Set version to a specific value
make install-hook             # Install pre-commit hook for version checking

Version Management

FastSkills uses Semantic Versioning (MAJOR.MINOR.PATCH). The version is managed centrally in the fastskills/__version__ file. The version is automatically read by fastskills/__init__.py (accessible via fastskills.__version__) and synchronized with pyproject.toml during package builds.

⚠️ Important: Version Updates are Required

All code changes must include a version number update. A pre-commit hook automatically enforces this requirement - commits with code changes will be rejected if the version number is not updated.

Version Increment Guidelines:

  • Patch Version (make patch-version-increment): Use for bug fixes and patches

    • Example: 0.1.0 → 0.1.1
    • Use when: Fixing bugs, patching security issues, or making small improvements

  • Minor Version (make minor-version-increment): Use for new features that don't break compatibility

    • Example: 0.1.0 → 0.2.0
    • Use when: Adding new features, enhancements, or improvements that maintain backward compatibility

  • Major Version (make major-version-increment): Use for breaking changes that may affect compatibility

    • Example: 0.1.0 → 1.0.0
    • Use when: Making changes that break backward compatibility, significant API changes, or major architectural changes

Version Management Commands:

# Show current version
make version

# Increment version (choose based on your changes)
make patch-version-increment   # 0.1.0 -> 0.1.1 (bug fixes)
make minor-version-increment   # 0.1.0 -> 0.2.0 (new features)
make major-version-increment   # 0.1.0 -> 1.0.0 (breaking changes)

# Set a specific version (for special cases)
make version-set VERSION=2.0.0

Pre-Commit Hook:

The project includes a pre-commit hook that automatically checks if the version number is updated when code changes are committed. This ensures version consistency across all commits.

Installing the Pre-Commit Hook:

# Install using make (recommended)
make install-hook

# Or manually
cp scripts/pre-commit-version-check.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

How It Works:

  1. When you commit code changes, the hook checks if any code files were modified (excluding docs, CI config, etc.)
  2. If code changes are detected, it verifies that fastskills/__version__ is also staged and updated
  3. If version is not updated, the commit is rejected with instructions on how to fix it
  4. If only documentation or CI files are changed, version update is not required

Example Workflow:

# 1. Make your code changes
vim fastskills/some_file.py

# 2. Stage your changes
git add fastskills/some_file.py

# 3. Update version (required!)
make patch-version-increment  # or minor/major depending on changes

# 4. Stage the version file
git add fastskills/__version__

# 5. Commit (hook will verify version is updated)
git commit -m "fix: description of your changes"

Version Management Summary:

Version Type Increment Method When to Use
Patch 🔧 Manual Bug fixes, patches, small improvements
Minor 🔧 Manual New features, enhancements (backward compatible)
Major 🔧 Manual Breaking changes, major API changes

Note: If you're using uv (recommended), all commands will automatically use the project's virtual environment. If you're using pip, make sure to activate your virtual environment first.

License

The licensing terms for FastSkills are currently being finalized. Until a dedicated LICENSE file is added to this repository, no license is granted for use, distribution, or modification beyond what is permitted by applicable law.

Related Links

About

An open-source, community-driven Agent framework that supports Claude's new Skills.

Resources

Readme
Activity
Custom properties

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages