Supported Source Formats for Installing Skills in the Skills CLI

The skills CLI supports ten distinct source formats for installing skills: local file paths, GitHub shorthand, full GitHub URLs, GitHub prefixed shorthand, GitLab URLs, GitLab prefixed shorthand, well-known HTTP endpoints, direct git URLs, source aliases, and fragment refs with skill filters.

The skills add command in the vercel-labs/skills repository accepts a wide variety of source specifications. All parsing logic is centralized in src/source-parser.ts, which converts each input string into a structured ParsedSource object. Understanding these supported source formats for installing skills helps you integrate both local and remote skill sources efficiently.

Local File System Paths

The parser identifies local paths through the isLocalPath() function at lines 10-20 in src/source-parser.ts. This check covers absolute paths, relative paths starting with ./ or ../, and Windows drive letters.

# Relative path

skills add ./my-skill

# Parent directory

skills add ../shared-skills/authentication

# Absolute path (Unix)

skills add /home/user/skills/my-skill

# Absolute path (Windows)

skills add C:\Users\me\skills\my-skill

GitHub Shorthand

The most compact remote format uses owner/repo syntax. The parser applies regex ^([^/]+)\/([^/]+)(?:\/(.+?))?\/?$ at lines 60-68 to match this pattern, with additional handling for @skill-name filters at lines 48-55.

# Basic shorthand

skills add vercel/nextjs-skill

# With subpath to specific skill directory

skills add vercel/nextjs-skill/path/to/skill

# With skill filter (installs only matching skill)

skills add vercel/nextjs-skill@mySkill

Full GitHub URLs

For explicit control over branches and paths, the parser supports complete GitHub URLs through three distinct patterns in src/source-parser.ts:

• githubTreeWithPathMatch (lines 64-74): .../tree/branch/path
• githubTreeMatch (lines 76-85): .../tree/branch
• githubRepoMatch (lines 87-96): Plain repository URL

# Plain repository URL

skills add https://github.com/vercel/nextjs-skill

# Specific branch

skills add https://github.com/vercel/nextjs-skill/tree/main

# Branch with subpath

skills add https://github.com/vercel/nextjs-skill/tree/main/agents/hello

GitHub Prefixed Shorthand

The github: prefix provides an alternative to raw shorthand, handled by githubPrefixMatch at line 45 of src/source-parser.ts. The parser strips the prefix and reprocesses the remainder recursively.

skills add github:vercel/nextjs-skill
skills add github:vercel/nextjs-skill@mySkill

GitLab URLs and Shorthand

GitLab support mirrors GitHub's structure with adaptations for GitLab's URL patterns. The parser implements:

• gitlabTreeWithPathMatch (lines 99-115): /-/tree/branch/path
• gitlabTreeMatch (lines 117-127): /-/tree/branch
• gitlabRepoMatch (lines 129-144): Plain repository URL, including sub-groups

The gitlab: prefix shorthand (lines 52-63) transforms to HTTPS URLs.

# Full GitLab URL with subpath

skills add https://gitlab.com/group/subgroup/repo/-/tree/main/agents/hello

# GitLab prefixed shorthand

skills add gitlab:group/subgroup/repo

Well-Known HTTP Endpoints

Non-git HTTP sources are supported through isWellKnownUrl() at lines 92-115 in src/source-parser.ts. This filter excludes known git hosts and .git suffixes, allowing arbitrary HTTPS URLs that serve skill definitions.

skills add https://example.com/.well-known/agent-skills/index.json

Direct Git URLs

As a fallback, any URL resembling a raw git repository (SSH, HTTP, or other protocols) returns {type: 'git', url: input} at lines 182-188 of src/source-parser.ts.

# SSH git URL

skills add git@github.com:vercel/nextjs-skill.git

# HTTP git URL

skills add https://git.example.com/skills/authentication.git

Source Aliases and Fragment Refs

The parser supports two additional convenience features:

Source aliases defined in SOURCE_ALIASES (lines 27-30) rewrite inputs before parsing:

skills add coinbase/agentWallet  # Rewrites to canonical URL

Fragment refs and skill filters (parseFragmentRef and appendFragmentRef, lines 81-119) append to any source format:

# Fragment ref (checks out specific tag/branch)

skills add vercel/nextjs-skill#v1.2.3

# Combined fragment ref and skill filter

skills add vercel/nextjs-skill#v1.2.3@mySkill

Summary

• Local paths: Absolute, relative (./, ../), and Windows drive formats
• GitHub shorthand: owner/repo with optional subpaths and @skill filters
• GitHub URLs: Full HTTPS URLs with branch and path specifications
• GitHub prefixed: github:owner/repo alternative syntax
• GitLab support: Mirror of GitHub with /-/tree/ URL patterns and gitlab: prefix
• Well-known endpoints: Arbitrary HTTPS URLs excluding git hosts
• Direct git URLs: SSH and HTTP git protocol fallbacks
• Aliases and filters: Source rewriting and fragment-based refinements

Frequently Asked Questions

How does the skills CLI distinguish between a local path and a GitHub shorthand?

The isLocalPath() function in src/source-parser.ts (lines 10-20) checks for path.isAbsolute(), ./ or ../ prefixes, and Windows drive letter patterns (C:\ or C:/). If any match, the input is treated as a local file system path. Otherwise, the parser attempts GitHub shorthand and URL matching.

Can I install a skill from a specific branch or tag?

Yes. Append a fragment ref using # syntax to any source format. For example: skills add vercel/nextjs-skill#v1.2.3 or skills add https://github.com/vercel/nextjs-skill/tree/develop#main. The parseFragmentRef function (lines 81-119 in src/source-parser.ts) extracts these references for checkout during installation.

Does the skills CLI support private GitHub repositories?

Private repositories are supported through direct git URLs using SSH authentication: skills add git@github.com:owner/private-repo.git. The parser's fallback logic (lines 182-188) returns {type: 'git', url: input} for any URL pattern not matching other categories, allowing SSH and authenticated HTTPS protocols to pass through to the installation layer in src/install.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}