CLI Reference

January 8, 2026 · View on GitHub

SkillPort provides a command-line interface for managing Agent Skills.

The MCP server (indexed search) is provided as a separate command/package: skillport-mcp.

Overview
Commands
- init - Initialize project
- add - Add skills
- update - Update skills
- list - List installed skills
- show - Show skill details
- meta - Manage frontmatter metadata
- remove - Remove skills
- validate - Validate skills
- doc - Generate AGENTS.md
MCP Server
- skillport-mcp - Start MCP server
Exit Codes
Configuration

Overview

skillport <command> [options]

# Global overrides (CLI > env > default)
skillport --skills-dir ./skills add hello-world
# Place global flags before the subcommand (e.g., skillport --skills-dir ... add ...)

Note: skillport is CLI-only. Use skillport-mcp to run the MCP server.

Global options (all commands)

Option	Description	Notes
`--skills-dir`	Override skills directory path	Applies to all commands in the invocation
(none)	Index settings	Index settings are MCP-server-only (`skillport-mcp`)

Precedence: CLI flag > environment variable (SKILLPORT_SKILLS_DIR) > default (~/.skillport/skills).

Commands

skillport init

Initialize SkillPort for a project. Creates configuration and generates skills to instruction files.

skillport init [options]

What it does

Creates .skillportrc configuration file
Creates skills directory if it doesn't exist
Updates instruction files (AGENTS.md, etc.) with skills table

Options

Option	Description	Default
`--skills-dir`, `-d`	Skills directory path	Interactive selection
`--instructions`, `-i`	Instruction files to update (repeatable)	Interactive selection
`--no-instructions`, `--skip-instructions`	Skip updating instruction files	`false`
`--yes`, `-y`	Skip prompts, use defaults	`false`

Interactive Mode

When options are not specified, init prompts for configuration:

$ skillport init

╭──────────────────────────────────────────────────────────────╮
│              ⚓ SkillPort  v0.3.0                             │
│     🚢 All Your Agent Skills in One Place                    │
│                                                              │
│     🚀 Initialize your project for Agent Skills              │
╰──────────────────────────────────────────────────────────────╯

? Where are your skills located?
  [1] ~/.skillport/skills (default)
  [2] .claude/skills (Claude Code)
  [3] ~/.codex/skills (Codex)
  [4] .skills
  [5] Custom path...

? Which instruction files to update? (comma-separated)
  [1] AGENTS.md (Codex, Cursor, Windsurf)
  [2] GEMINI.md (Gemini CLI, Antigravity)
  [3] None (skip)
  [4] Custom...

✓ Created .skillportrc
✓ Created ~/.skillport/skills/
✓ Indexed 3 skill(s)
✓ Updated AGENTS.md

✨ Ready! Start your coding agent to use skills.
   Run 'skillport add hello-world' to add your first skill

Non-Interactive Mode

# Use defaults (skills: ~/.skillport/skills, instructions: AGENTS.md)
skillport init --yes

# Skip instruction file updates
skillport init --no-instructions

# Specify explicitly
skillport init --skills-dir .skills --instructions AGENTS.md --instructions GEMINI.md

Generated .skillportrc

# SkillPort Configuration
# See: https://github.com/gotalab/skillport

skills_dir: ~/.skillport/skills
instructions:
  - AGENTS.md
  - GEMINI.md

The instructions list is used by skillport doc --all to update all files at once.

skillport add

Add skills from various sources.

skillport add <source> [options]

Sources

Type	Example	Description
Built-in	`hello-world`	Sample skill bundled with SkillPort
Built-in	`template`	Starter template for creating skills
Local	`./my-skill/`	Single skill directory
Local	`./my-collection/`	Directory containing multiple skills
Local	`./mixed/`	Directory containing both skill directories and zip files
Zip	`./my-skill.zip`	Single skill in zip format (1 zip = 1 skill)
GitHub	`user/repo`	Shorthand format (auto-detects default branch)
GitHub	`user/repo skills`	Shorthand with path(s) - single download, multiple paths
GitHub	`https://github.com/user/repo`	Full URL (auto-detects default branch)
GitHub	`https://github.com/user/repo/tree/main/skills`	Full URL with specific directory

Zip file support:

Each zip file must contain exactly one skill

Zip files in a directory are automatically detected and extracted

Useful for skills exported from Claude.ai

GitHub shorthand (owner/repo):

Simpler syntax: skillport add anthropics/skills

Supports multiple paths: skillport add owner/repo skills examples (single download)

Local paths take priority (if ./owner/repo exists, it's treated as local)

GitHub URL support:

Works with or without trailing slash

Auto-detects default branch when not specified

Private repositories: use gh auth login (recommended) or set GITHUB_TOKEN

Options

Option	Description	Default
`--force`, `-f`	Overwrite existing skills	`false`
`--yes`, `-y`	Skip interactive prompts (for CI/automation)	`false`
`--keep-structure/--no-keep-structure`	Preserve directory structure as namespace	Interactive
`--namespace`, `-n`	Custom namespace	source directory name
`--name`	Override skill name (single skill only)	from SKILL.md
`--json`	Output as JSON (for scripting/AI agents)	`false`

Interactive Mode

When specifying a local path or GitHub URL without --keep-structure or --namespace, interactive mode lets you choose where to add skills.

$ skillport add ./my-collection/

Found 3 skill(s): skill-a, skill-b, skill-c
Where to add?
  [1] Flat       → skills/skill-a/, skills/skill-b/, ...
  [2] Namespace  → skills/<ns>/skill-a/, ...
  [3] Skip
Choice [1/2/3] (1):

Choice	Behavior
`1` Flat	Add flat (`--no-keep-structure` equivalent)
`2` Namespace	Add with namespace. Prompts for namespace name
`3` Skip	Exit without adding

Note: Built-in skills (hello-world, template) skip interactive mode.

Examples

Built-in skills:

# Add sample skill
skillport add hello-world

# Add template for creating your own
skillport add template

Local directory:

# Single skill
skillport add ./my-skill/

# Multiple skills - interactive mode
skillport add ./my-collection/

# Multiple skills - flat (skip interactive)
skillport add ./my-collection/ --no-keep-structure
# → skills/skill-a/, skills/skill-b/, skills/skill-c/

# Multiple skills - preserve structure
skillport add ./my-collection/ --keep-structure
# → skills/my-collection/skill-a/, skills/my-collection/skill-b/

# Multiple skills - custom namespace
skillport add ./my-collection/ --keep-structure --namespace team-tools
# → skills/team-tools/skill-a/, skills/team-tools/skill-b/

Zip files:

# Single zip file (exported from Claude.ai, etc.)
skillport add ./my-skill.zip

# Directory containing both zips and skill directories
skillport add ./mixed/
# ./mixed/
# ├── a.zip         → extracted and added
# ├── b.zip         → extracted and added
# ├── skill-c/      → added as usual
# └── skill-d/      → added as usual

# Zip with namespace
skillport add ./my-skill.zip --namespace my-ns
# → skills/my-ns/my-skill/

GitHub (shorthand):

# All skills from repository root
skillport add anthropics/skills

# Specific path(s) within repository - single download, efficient
skillport add anthropics/skills skills
skillport add owner/repo skills examples  # multiple paths

# Force overwrite existing
skillport add anthropics/skills --force

GitHub (full URL):

# Specific skill from repository
skillport add https://github.com/user/repo/tree/main/skills/code-review

# All skills from repository
skillport add https://github.com/user/repo

# Force overwrite existing
skillport add https://github.com/user/repo --force

Output

All succeeded:

  ✓ Added 'skill-a'
  ✓ Added 'skill-b'
Added 2 skill(s)

Some skipped (already exists):

  ✓ Added 'skill-c'
  ⊘ Skipped 'skill-a' (exists)
  ⊘ Skipped 'skill-b' (exists)
Added 1, skipped 2 (use --force to overwrite)

skillport update

Update skills from their original sources (GitHub or local).

skillport update [skill-id] [options]

What it does

Checks for available updates from original sources
Detects local modifications (prevents accidental overwrites)
Updates skill files and tracks version history
Rebuilds the skill index after updates

Options

Option	Description	Default
`--all`, `-a`	Update all updatable skills	`false`
`--force`, `-f`	Overwrite local modifications	`false`
`--dry-run`, `-n`	Show what would be updated without making changes	`false`
`--check`, `-c`	Check for available updates without updating	`false`
`--json`	Output as JSON (for scripting/AI agents)	`false`

Default Behavior

When invoked without arguments, skillport update automatically enters check mode:

$ skillport update

Updates available:
  my-skill (github @ def5678)
  team/code-review (github @ abc1234) (local changes)

Run 'skillport update --all' to update all, or 'skillport update <skill-id>' for one.

Up to date: 3 skill(s)
Not updatable: 1 skill(s)
Untracked: 2 skill(s)
  → Use 'skillport add <source>' to track

Update all listed skills now? [y/N]:

If updates are available, you'll be prompted to update them interactively.

Untracked Skills

Skills that exist in the skills directory but were not added via skillport add are shown as "Untracked". These include:

Skills copied manually to the skills directory
Skills from older versions before origin tracking was added
Skills created directly in the skills directory

To track an untracked skill, add it from its original source:

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

Examples

Check for updates:

# Show available updates (default behavior)
skillport update

# Explicit check mode (non-interactive)
skillport update --check

Update skills:

# Update a single skill
skillport update my-skill

# Update all updatable skills
skillport update --all

# Force update despite local modifications
skillport update my-skill --force

# Preview changes without updating
skillport update --all --dry-run

JSON output (for scripting):

# Check updates as JSON
skillport update --check --json

# Bulk update with JSON output
skillport update --all --json

Update Sources

Skills track their original source (origin) and can be updated from:

Origin	Description
GitHub	Checks commit SHA, downloads only when changed
Local	Compares content hash with source directory
Zip	Checks file mtime, re-extracts and compares content hash when changed
Built-in	Cannot be updated (bundled with SkillPort)

Local Modification Detection

SkillPort tracks a content hash for each skill. If you manually edit a skill's files:

$ skillport update my-skill

⚠ Local modifications detected in 'my-skill'
  Use --force to overwrite local changes

Use --force to overwrite, or update the source and re-add the skill.

Output

Single skill updated:

  + Updated 'my-skill' (abc1234 -> def5678)
✓ Updated my-skill from github
Rebuilding index...

Bulk update:

  + Updated 'skill-a' (abc1234 -> def5678)
  + Updated 'skill-b'
  - 3 skill(s) already up to date
✓ Updated 2 skill(s)
Rebuilding index...

Already up to date:

  - 'my-skill' is already up to date

Exit Codes

Code	Meaning
0	Success (or no updates available)
1	Error or local modifications detected (without `--force`)

skillport list

List installed skills.

skillport list [options]

Options

Option	Description	Default
`--limit`, `-n`	Maximum number to display	`100`
`--json`	Output as JSON	`false`

Examples

# List all skills
skillport list

# Limit results
skillport list --limit 20

# JSON output for scripting
skillport list --json

Output Format

Default (table view):

                       Skills (5)
 ID                    Description
 hello-world           A simple hello world skill for testing…
 pdf                   Extract text from PDF files
 team/code-review      Code review checklist and guidelines

JSON:

{
  "skills": [
    {
      "id": "hello-world",
      "name": "hello-world",
      "description": "A simple hello world skill",
      "category": "example"
    }
  ],
  "total": 5
}

Search (MCP only)

skillport search is not provided in the CLI.

For discovery, run the MCP server (skillport-mcp) and use MCP tools:

search_skills(query)
load_skill(skill_id)

For local browsing without MCP, use skillport list + skillport show <id>.

skillport show

Show skill details.

skillport show <skill-id> [options]

Options

Option	Description	Default
`--json`	Output as JSON	`false`

Examples

# Show skill details
skillport show hello-world

# Show namespaced skill
skillport show team-tools/code-review

# JSON output
skillport show pdf --json

skillport meta

Manage SKILL.md frontmatter metadata for one or more skills.

skillport meta <subcommand> [options]

Subcommands

skillport meta set [SKILL_ID ...] <key> <value>
skillport meta bump [SKILL_ID ...] <key> (--major|--minor|--patch)
skillport meta unset [SKILL_ID ...] <key>
skillport meta show [SKILL_ID ...]

Key Mapping

If <key> starts with metadata., it is used as-is.
Otherwise it is mapped under metadata.<key>.

Examples:

author → metadata.author
skillport.category → metadata.skillport.category

Options

Option	Description	Default
`--all`	Target all skills	`false`
`--dry-run`	Show changes without writing (set/bump/unset)	`false`
`--json`	Output as JSON	`false`

Examples

# Show metadata
skillport meta show my-skill

# Set metadata.author
skillport meta set my-skill author gota

# Set nested metadata.skillport.category
skillport meta set my-skill skillport.category "devops"

# Bump metadata.version
skillport meta bump my-skill version --patch

# Unset metadata.author
skillport meta unset my-skill author

# Set the same key across multiple skills
skillport meta set skill-a skill-b author gota

# Bump version for multiple skills
skillport meta bump skill-a skill-b version --minor

# Unset across multiple skills (dry-run)
skillport meta unset skill-a skill-b author --dry-run

# Apply to all skills (dry-run)
skillport meta set --all author gota --dry-run

skillport remove

Remove installed skills.

skillport remove <skill-id> [options]

Options

Option	Description	Default
`--force`, `-f`	Skip confirmation	`false`
`--yes`, `-y`	Skip confirmation (alias for --force)	`false`
`--json`	Output as JSON (for scripting/AI agents)	`false`

Examples

# Remove with confirmation
skillport remove hello-world
# → Remove 'hello-world'? [y/N]

# Remove without confirmation
skillport remove hello-world --force

# Remove namespaced skill
skillport remove team-tools/code-review --force

skillport validate

Validate skill files against the Agent Skills specification.

skillport validate [target] [options]

Target Types

Type	Example	Description
(none)	`skillport validate`	Validate all skills in skills directory
Skill ID	`skillport validate hello-world`	Validate specific skill by ID
Path (skill)	`skillport validate ./my-skill/`	Validate single skill directory
Path (dir)	`skillport validate ./skills/`	Validate all skills in directory

Note: Path-based validation works without the index—useful for CI/CD and pre-add validation.

Options

Option	Description	Default
`--json`	Output as JSON (for scripting/AI agents)	`false`

Validation Rules

Fatal (validation fails)

Rule	Description
`name` required	Missing name in frontmatter
`description` required	Missing description in frontmatter
name = directory	Name doesn't match directory name
name ≤ 64 chars	Name is too long
name pattern	Only lowercase letters, digits, `-` allowed (Unicode supported)
no leading/trailing hyphen	Name cannot start or end with `-`
no consecutive hyphens	Name cannot contain `--`
description ≤ 1024 chars	Description is too long
unexpected frontmatter keys	Only allowed keys (see below)
compatibility ≤ 500 chars	Compatibility field is too long

Allowed frontmatter keys:

Source	Keys
agentskills.io	`name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`
Claude Code 2.1.0+	`model`, `context`, `agent`, `hooks`, `user-invocable`

Warning (warning only)

Rule	Description
SKILL.md ≤ 500 lines	File is too long

Examples

# Validate all skills in index
skillport validate

# Validate specific skill by ID
skillport validate hello-world

# Validate by path (single skill) - works without index
skillport validate ./my-skill/

# Validate by path (directory) - scans all skills
skillport validate ./skills/

# JSON output for CI/CD
skillport validate ./skills/ --json

Output

All valid:

✓ All 3 skill(s) pass validation

Issues found:

broken-skill
  ✗ (fatal) frontmatter.name 'wrong-name' doesn't match directory 'broken-skill'
  ⚠ (warning) SKILL.md: 600 lines (recommended ≤500)

╭─────────────────────────────────────╮
│ Checked 3 skill(s): 1 fatal, 1 warning │
╰─────────────────────────────────────╯

Exit Codes

Code	Meaning
0	All valid (no fatal issues)
1	Fatal issues found

Deprecated Alias

The lint command is deprecated. Use validate instead:

# Deprecated (still works with warning)
skillport lint

# Use this instead
skillport validate

MCP Server

skillport-mcp

Start the MCP server (indexed search).

skillport-mcp [options]

Options

Option	Description	Default
`--http`	Run as HTTP server (Remote mode)	`false`
`--host`	HTTP server host (only with --http)	`127.0.0.1`
`--port`	HTTP server port (only with --http)	`8000`
`--reindex`	Force reindex on startup	`false`
`--skip-auto-reindex`	Skip automatic reindex check	`false`

Transport Modes

Mode	Command	Tools
Local (stdio)	`skillport-mcp`	`search_skills`, `load_skill`
Remote (HTTP)	`skillport-mcp --http`	+ `read_skill_file`

Examples

# Local mode (stdio) - for Claude Code, Cursor
skillport-mcp

# Remote mode (HTTP) - for network access
skillport-mcp --http

# Remote mode with custom host/port
skillport-mcp --http --host 0.0.0.0 --port 8000

# Start with forced reindex
skillport-mcp --reindex

skillport doc

Generate skill documentation for instruction files (AGENTS.md, etc.).

skillport doc [options]

Options

Option	Description	Default
`--output`, `-o`	Output file path	`./AGENTS.md`
`--all`, `-a`	Update all files in `.skillportrc` `instructions`	`false`
`--append/--replace`	Append to existing file or replace entirely	`--append`
`--skills`	Comma-separated skill IDs to include	all
`--category`	Comma-separated categories to include	all
`--format`	Output format: `xml` or `markdown`	`xml`
`--mode`, `-m`	Target agent type: `cli` or `mcp`	`cli`
`--force`, `-f`	Overwrite without confirmation	`false`

Note: When --all is specified, --output is ignored and all files listed in .skillportrc instructions are updated.

Mode

Mode	Description
`cli`	For agents using CLI commands (`skillport show <id>`)
`mcp`	For agents using MCP tools (`search_skills`, `load_skill`)

Examples

# Generate skill docs to ./AGENTS.md
skillport doc

# Update all instruction files from .skillportrc
skillport doc --all

# Generate to specific file
skillport doc -o .claude/AGENTS.md

# Force overwrite without confirmation
skillport doc -f

# Filter by category
skillport doc --category development,testing

# Filter by skill IDs
skillport doc --skills pdf,code-review

# Use markdown format (no XML tags)
skillport doc --format markdown

# Generate for MCP-enabled agents
skillport doc --mode mcp

# Replace entire file instead of appending
skillport doc --replace

Output Format

The generated block includes:

Markers —  and  for safe updates
Instructions — Workflow and tips for agents
Skills Table — ID, Description, Category

CLI mode output:

<!-- SKILLPORT_START -->
<available_skills>

## SkillPort Skills

Skills are reusable expert knowledge...

### Workflow

1. **Find a skill** - Check the table below...
2. **Get instructions** - Run `skillport show <skill-id>`...
3. **Follow the instructions** - Execute the steps...

### Tips
...

### Available Skills

| ID | Description | Category |
|----|-------------|----------|
| pdf | Extract text from PDF files | tools |

</available_skills>
<!-- SKILLPORT_END -->

MCP mode output:

<!-- SKILLPORT_START -->
<available_skills>

## SkillPort Skills
...

### Workflow

1. **Search** - Call `search_skills(query)`...
2. **Load** - Call `load_skill(skill_id)`...
3. **Execute** - Follow the instructions...

### Tools

- `search_skills(query)` - Find skills by task description
- `load_skill(id)` - Get full instructions and path
- `read_skill_file(id, file)` - Read templates or config files

### Tips
...

### Available Skills
...

</available_skills>
<!-- SKILLPORT_END -->

Update Behavior

Scenario	Behavior
File doesn't exist	Creates new file (including parent directories)
File has markers	Replaces content between markers
File without markers + `--append`	Appends to end
File without markers + `--replace`	Replaces entire file

Exit Codes

Code	Meaning
0	Success
1	Error (invalid input, not found, validation failed, etc.)

Configuration

For full configuration options, see Configuration Guide.

Quick Reference

CLI commands resolve skills_dir in this order:

CLI flags — --skills-dir
Environment variables — SKILLPORT_SKILLS_DIR
Project config — .skillportrc or pyproject.toml [tool.skillport]
Default — ~/.skillport/skills

Key Environment Variables

Variable	Description
`SKILLPORT_SKILLS_DIR`	Skills directory
(MCP server) `SKILLPORT_DB_PATH`	Index location (used by `skillport-mcp`)

GitHub Authentication

SkillPort automatically detects GitHub authentication using the following fallback chain:

GH_TOKEN — Environment variable (fine-grained PAT recommended)
GITHUB_TOKEN — Environment variable (classic PAT)
gh auth token — GitHub CLI authentication

Recommended: If you have GitHub CLI installed and authenticated (gh auth login), SkillPort will automatically use your credentials. No additional configuration needed.

# One-time setup (if not already done)
gh auth login

# Now private repos just work
skillport add https://github.com/your-org/private-skills

Alternative: Set an environment variable with a Personal Access Token:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Required token scopes:

Classic PAT: repo scope
Fine-grained PAT: Contents: Read permission