SkillPort Documentation

SkillPort uses a full-text search (FTS) strategy based on the BM25 algorithm via Tantivy. This provides fast, privacy-preserving discovery of skills without requiring external API keys.

Search Features:

• Indexed Fields: Searches across skill names, descriptions, tags, and categories.
• Fallback Chain: If the BM25 full-text search returns no results, the system automatically falls back to a substring match to ensure the agent almost always finds a relevant result.
• Efficiency: Designed to handle 100+ skills efficiently, mirroring the pattern used by Anthropic's Tool Search Tool.

When using the SkillPort CLI, the skills_dir is resolved using the following priority order:

1. CLI flags: --skills-dir
2. Environment variables: SKILLPORT_SKILLS_DIR
3. .skillportrc: Project-specific YAML configuration
4. pyproject.toml: [tool.skillport] section
5. Default: ~/.skillport/skills

SkillPort uses a progressive disclosure model to prevent context window bloat. Instead of loading all instructions upfront, it loads information in three stages:

1. Level 1 (Metadata): Loaded at server start. Contains only the name and description (~100 tokens per skill). This allows for efficient searching.
2. Level 2 (Instructions): Loaded via load_skill(). Contains the full instructions from the SKILL.md body (< 5,000 tokens).
3. Level 3 (Resources): Loaded via read_skill_file(). Contains specific templates, configurations, or reference files (variable token cost).

This approach allows an agent to manage hundreds of skills while only consuming a fraction of the tokens required by traditional system prompts.

It is important to distinguish between Model Context Protocol (MCP) and Agent Skills to design your agentic workflows correctly. They are complementary layers:

• MCP (Data Access): Provides the connection to raw data or APIs (e.g., "Connect to the GitHub API").
• Skills (Procedural Knowledge): Provides the instructions on how to use that data (e.g., "When reviewing PRs, check these 5 specific things").

In a typical workflow, an MCP server provides the tool/API access, and a Skill provides the high-level reasoning and procedural steps to execute tasks using those tools.

You can control which skills are visible to different AI agents (e.g., an IDE agent vs. a Chat agent) by configuring the SKILLPORT_ENABLED_CATEGORIES environment variable in your MCP client configuration. This allows you to serve different specialized skill sets from the same repository.

Example configuration for an MCP client (like Claude Desktop or Cursor):

{
  "mcpServers": {
    "skillport-ide": {
      "env": { "SKILLPORT_ENABLED_CATEGORIES": "development" }
    },
    "skillport-chat": {
      "env": { "SKILLPORT_ENABLED_CATEGORIES": "writing,research" }
    }
  }
}

For CLI usage, you can define project-specific settings in a .skillportrc file (YAML) or within the [tool.skillport] section of a pyproject.toml file. This is useful for defining where your skills are located and which instruction files should be updated during a sync.

Note: The MCP server (skillport-mcp) does not read these project configuration files. Use environment variables for MCP configuration instead.

# .skillportrc
skills_dir: .skills
instructions:
  - AGENTS.md
  - GEMINI.md

# pyproject.toml
[tool.skillport]
skills_dir = ".skills"
instructions = ["AGENTS.md", "GEMINI.md"]

When writing the Markdown content of SKILL.md, follow these best practices to optimize for AI agents:

1. Keep Instructions Concise

Target under 5,000 tokens. Use bullet points, numbered lists, and clear headings instead of long paragraphs.

2. Use Path-Based References

Do not inline large blocks of code in SKILL.md as it wastes context. Instead, use the {path} placeholder to reference files within the skill directory. The {path} placeholder is automatically replaced with the skill's absolute directory path.

Example:

Run the validation script:
```bash
python {path}/scripts/validate.py input.txt

### 3. Provide Context for Scripts
Explain what scripts do and their arguments without including the source code itself.

The skillport CLI is used for managing Agent Skills. When using global flags, you must place them before the subcommand.

Precedence Rules: Global settings follow this order of priority: CLI flag > environment variable (SKILLPORT_SKILLS_DIR) > default (~/.skillport/skills).

Global Options:

# Correct usage: global flag before subcommand
skillport --skills-dir ./skills add hello-world

# Incorrect usage: global flag after subcommand
skillport add hello-world --skills-dir ./skills

You can install skills directly from a GitHub repository using the skillport add command.

Single Skill Repository

If the repository contains a single skill (with SKILL.md at the root):

skillport add https://github.com/user/pdf-extractor

Multi-Skill Repository

If the repository is a collection of skills (each in its own subdirectory):

skillport add https://github.com/user/my-skills-repo

# Install a single skill repo
skillport add https://github.com/user/pdf-extractor

# Install a collection of skills
skillport add https://github.com/user/my-skills-repo