Showing preview only (495K chars total). Download the full file or copy to clipboard to get everything.
Repository: vercel-labs/skills
Branch: main
Commit: fc3b8b8d68bd
Files: 72
Total size: 471.8 KB
Directory structure:
gitextract_8sxvogv3/
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── agent-request.yml
│ │ ├── bug-report.yml
│ │ ├── config.yml
│ │ └── feature-request.yml
│ ├── RELEASE_TEMPLATE.md
│ └── workflows/
│ ├── agents.yml
│ ├── ci.yml
│ └── publish.yml
├── .gitignore
├── .husky/
│ └── pre-commit
├── .prettierrc
├── AGENTS.md
├── README.md
├── ThirdPartyNoticeText.txt
├── bin/
│ └── cli.mjs
├── build.config.mjs
├── package.json
├── scripts/
│ ├── execute-tests.ts
│ ├── generate-licenses.ts
│ ├── sync-agents.ts
│ └── validate-agents.ts
├── skills/
│ └── find-skills/
│ └── SKILL.md
├── src/
│ ├── add-prompt.test.ts
│ ├── add.test.ts
│ ├── add.ts
│ ├── agents.ts
│ ├── cli.test.ts
│ ├── cli.ts
│ ├── constants.ts
│ ├── find.ts
│ ├── git.ts
│ ├── init.test.ts
│ ├── install.ts
│ ├── installer.ts
│ ├── list.test.ts
│ ├── list.ts
│ ├── local-lock.ts
│ ├── plugin-manifest.ts
│ ├── prompts/
│ │ └── search-multiselect.ts
│ ├── providers/
│ │ ├── index.ts
│ │ ├── registry.ts
│ │ ├── types.ts
│ │ └── wellknown.ts
│ ├── remove.test.ts
│ ├── remove.ts
│ ├── skill-lock.ts
│ ├── skills.ts
│ ├── source-parser.test.ts
│ ├── source-parser.ts
│ ├── sync.ts
│ ├── telemetry.ts
│ ├── test-utils.ts
│ └── types.ts
├── tests/
│ ├── cross-platform-paths.test.ts
│ ├── dist.test.ts
│ ├── full-depth-discovery.test.ts
│ ├── installer-symlink.test.ts
│ ├── list-installed.test.ts
│ ├── local-lock.test.ts
│ ├── openclaw-paths.test.ts
│ ├── plugin-grouping.test.ts
│ ├── plugin-manifest-discovery.test.ts
│ ├── remove-canonical.test.ts
│ ├── sanitize-name.test.ts
│ ├── skill-matching.test.ts
│ ├── skill-path.test.ts
│ ├── source-parser.test.ts
│ ├── subpath-traversal.test.ts
│ ├── sync.test.ts
│ ├── wellknown-provider.test.ts
│ └── xdg-config-paths.test.ts
└── tsconfig.json
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/ISSUE_TEMPLATE/agent-request.yml
================================================
name: Agent Request
description: Request support for a new coding agent
title: "[Agent]: "
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Thanks for requesting a new agent! Please provide the details below.
- type: input
id: agent-name
attributes:
label: Agent Name
description: The name of the coding agent
placeholder: e.g., Cursor, Claude Code
validations:
required: true
- type: input
id: agent-url
attributes:
label: Skills Documentation URL
description: Link to the agent's skills documentation
placeholder: https://example.com/docs/skills
validations:
required: true
- type: input
id: skills-dir
attributes:
label: Project Skills Directory
description: Where skills are stored at the project level
placeholder: e.g., .cursor/skills
validations:
required: true
- type: input
id: global-skills-dir
attributes:
label: Global Skills Directory
description: Where skills are stored at the user/global level
placeholder: e.g., ~/.cursor/skills
validations:
required: true
- type: input
id: detection-path
attributes:
label: Detection Path
description: Path to check if the agent is installed (usually a config directory)
placeholder: e.g., ~/.cursor
validations:
required: true
================================================
FILE: .github/ISSUE_TEMPLATE/bug-report.yml
================================================
name: Bug Report
description: Report a bug or issue
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for reporting a bug! Please provide as much detail as possible.
- type: textarea
id: description
attributes:
label: Description
description: A clear description of the bug
placeholder: What happened?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to Reproduce
description: How can we reproduce this issue?
placeholder: |
1. Run `npx add-skill ...`
2. Select ...
3. See error
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
description: What did you expect to happen?
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual Behavior
description: What actually happened?
validations:
required: true
- type: input
id: version
attributes:
label: Version
description: What version of add-skill are you using?
placeholder: e.g., 1.0.8
validations:
required: false
- type: input
id: node-version
attributes:
label: Node.js Version
description: What version of Node.js are you using?
placeholder: e.g., 20.10.0
validations:
required: false
- type: dropdown
id: os
attributes:
label: Operating System
options:
- macOS
- Windows
- Linux
- Other
validations:
required: false
- type: textarea
id: logs
attributes:
label: Logs / Error Output
description: Paste any relevant error messages or logs
render: shell
validations:
required: false
================================================
FILE: .github/ISSUE_TEMPLATE/config.yml
================================================
blank_issues_enabled: true
contact_links:
- name: Documentation
url: https://github.com/vercel-labs/add-skill#readme
about: Check the README for usage instructions
- name: Agent Skills Specification
url: https://agentskills.io/home
about: Learn about the Agent Skills specification
================================================
FILE: .github/ISSUE_TEMPLATE/feature-request.yml
================================================
name: Feature Request
description: Suggest a new feature or improvement
title: "[Feature]: "
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Thanks for suggesting a feature! Please describe your idea below.
- type: textarea
id: problem
attributes:
label: Problem
description: What problem does this feature solve?
placeholder: I'm always frustrated when...
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed Solution
description: How would you like this to work?
placeholder: Describe your ideal solution
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives Considered
description: Have you considered any alternative solutions or workarounds?
validations:
required: false
- type: textarea
id: context
attributes:
label: Additional Context
description: Any other context, screenshots, or examples
validations:
required: false
================================================
FILE: .github/RELEASE_TEMPLATE.md
================================================
## Changelog
${CHANGELOG}
## Contributors
${CONTRIBUTORS}
================================================
FILE: .github/workflows/agents.yml
================================================
name: Agents CI
on:
pull_request:
paths:
- "src/agents.ts"
push:
branches: [main]
paths:
- "src/agents.ts"
concurrency:
group: agents-${{ github.ref }}
cancel-in-progress: true
jobs:
validate-agents:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Enable Corepack
run: corepack enable
- name: Enable Corepack
run: corepack enable
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: lts/*
cache: pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Validate agents
run: node scripts/validate-agents.ts
sync-agents:
needs: validate-agents
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Enable Corepack
run: corepack enable
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: lts/*
cache: pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Sync agents
run: pnpm exec node scripts/sync-agents.ts
- name: Commit changes
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git diff --quiet README.md package.json || (git add README.md package.json && git commit -m "chore: update README and package.json with latest agents")
- name: Push changes
run: git push
================================================
FILE: .github/workflows/ci.yml
================================================
name: CI
on:
pull_request:
paths-ignore:
- "**/*.md"
push:
branches: [main]
paths-ignore:
- "**/*.md"
jobs:
checks:
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- name: Checkout repo
uses: actions/checkout@v6
- name: Enable Corepack
run: corepack enable
- name: Setup Node
uses: actions/setup-node@v6
with:
node-version: lts/*
cache: pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Type check
run: pnpm build
- name: Prettier
if: matrix.os == 'ubuntu-latest'
run: pnpm format:check
- name: Tests
run: pnpm test
================================================
FILE: .github/workflows/publish.yml
================================================
name: Publish
on:
push:
branches: [main]
tags:
- 'v*'
paths-ignore:
- '**/*.md'
workflow_dispatch:
inputs:
bump:
description: 'Version bump type'
required: true
type: choice
options:
- patch
- minor
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
steps:
- name: Checkout repo
uses: actions/checkout@v6
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Enable Corepack
run: corepack enable
- name: Setup Node
uses: actions/setup-node@v6
with:
node-version: lts/*
cache: pnpm
registry-url: 'https://registry.npmjs.org'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Build
run: pnpm build
- name: Determine version bump type
id: version
run: |
# If tag push, skip version bump (already versioned)
if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
echo "bump=skip" >> $GITHUB_OUTPUT
echo "Tag push - skipping version bump, will publish directly"
exit 0
fi
# If manually triggered, use the input value
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
echo "bump=${{ inputs.bump }}" >> $GITHUB_OUTPUT
echo "Manual trigger - will bump ${{ inputs.bump }} version"
exit 0
fi
# Get the latest version tag
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LATEST_TAG" ]; then
# No tags found, use all commits
COMMITS=$(git log --format=%s)
else
# Get commits since the latest tag
COMMITS=$(git log ${LATEST_TAG}..HEAD --format=%s)
fi
echo "Commits since last tag:"
echo "$COMMITS"
# Check for explicit version bump markers
if echo "$COMMITS" | grep -q "\[minor\]"; then
echo "bump=minor" >> $GITHUB_OUTPUT
echo "Found [minor] - will bump minor version"
elif echo "$COMMITS" | grep -q "\[patch\]"; then
echo "bump=patch" >> $GITHUB_OUTPUT
echo "Found [patch] - will bump patch version"
else
echo "bump=none" >> $GITHUB_OUTPUT
echo "No version marker found - skipping release"
fi
- name: Configure git
if: steps.version.outputs.bump != 'none' && steps.version.outputs.bump != 'skip'
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Reset generated files
if: steps.version.outputs.bump != 'none' && steps.version.outputs.bump != 'skip'
run: |
# Reset any changes to generated files (e.g., ThirdPartyNoticeText.txt)
# that may differ between local and CI builds
git checkout -- ThirdPartyNoticeText.txt || true
- name: Bump version
if: steps.version.outputs.bump != 'none' && steps.version.outputs.bump != 'skip'
run: |
npm version ${{ steps.version.outputs.bump }} -m "v%s"
- name: Push changes
if: steps.version.outputs.bump != 'none' && steps.version.outputs.bump != 'skip'
run: |
git push
git push --tags
- name: Publish to npm
id: publish
if: steps.version.outputs.bump != 'none'
run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Create GitHub Release
if: steps.publish.outcome == 'success'
run: |
VERSION=$(node -p "require('./package.json').version")
# Get changelog from merged PRs since last tag
LATEST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
if [ -z "$LATEST_TAG" ]; then
SINCE=""
else
SINCE=$(git log -1 --format=%cI ${LATEST_TAG})
fi
# Fetch merged PRs and format as changelog
if [ -z "$SINCE" ]; then
PRS=$(gh pr list --state merged --json number,title,author --limit 100)
else
PRS=$(gh pr list --state merged --search "merged:>=${SINCE}" --json number,title,author --limit 100)
fi
CHANGELOG=$(echo "$PRS" | jq -r '.[] | "- \(.title) (#\(.number))"')
CONTRIBUTORS=$(echo "$PRS" | jq -r '.[].author.login' | sort -u | sed 's/^/@/' | paste -sd ', ' -)
# Generate release notes from template
export VERSION CHANGELOG CONTRIBUTORS
envsubst < .github/RELEASE_TEMPLATE.md > release-notes.md
gh release create "v${VERSION}" --notes-file release-notes.md
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
================================================
FILE: .gitignore
================================================
# dependencies (bun install)
node_modules
# output
out
dist
*.tgz
# code coverage
coverage
*.lcov
# logs
logs
_.log
report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
# caches
.eslintcache
.cache
*.tsbuildinfo
# IntelliJ based IDEs
.idea
# Finder (MacOS) folder config
.DS_Store
*.log
package-lock.json
.codebuddy/
.agent/
.agents/
.claude/
.cursor/
.gemini/
.github/skills/
.opencode/
.qoder/
.qwen/
.trae/
.vscode/
bin/_chunks/
bin/cli-wrapper.mjs
bin/cli.d.mts
================================================
FILE: .husky/pre-commit
================================================
pnpm lint-staged
================================================
FILE: .prettierrc
================================================
{
"semi": true,
"singleQuote": true,
"trailingComma": "es5",
"printWidth": 100,
"tabWidth": 2
}
================================================
FILE: AGENTS.md
================================================
# AGENTS.md
This file provides guidance to AI coding agents working on the `skills` CLI codebase.
## Project Overview
`skills` is the CLI for the open agent skills ecosystem.
## Commands
| Command | Description |
| ----------------------------- | --------------------------------------------------- |
| `skills` | Show banner with available commands |
| `skills add <pkg>` | Install skills from git repos, URLs, or local paths |
| `skills experimental_install` | Restore skills from skills-lock.json |
| `skills experimental_sync` | Sync skills from node_modules into agent dirs |
| `skills list` | List installed skills (alias: `ls`) |
| `skills check` | Check for available skill updates |
| `skills update` | Update all skills to latest versions |
| `skills init [name]` | Create a new SKILL.md template |
Aliases: `skills a` works for `add`. `skills i`, `skills install` (no args) restore from `skills-lock.json`. `skills ls` works for `list`. `skills experimental_install` restores from `skills-lock.json`. `skills experimental_sync` crawls `node_modules` for skills.
## Architecture
```
src/
├── cli.ts # Main entry point, command routing, init/check/update
├── cli.test.ts # CLI tests
├── add.ts # Core add command logic
├── add-prompt.test.ts # Add prompt behavior tests
├── add.test.ts # Add command tests
├── constants.ts # Shared constants
├── find.ts # Find/search command
├── list.ts # List installed skills command
├── list.test.ts # List command tests
├── remove.ts # Remove command implementation
├── remove.test.ts # Remove command tests
├── agents.ts # Agent definitions and detection
├── installer.ts # Skill installation logic (symlink/copy) + listInstalledSkills
├── skills.ts # Skill discovery and parsing
├── skill-lock.ts # Global lock file management (~/.agents/.skill-lock.json)
├── local-lock.ts # Local lock file management (skills-lock.json, checked in)
├── sync.ts # Sync command - crawl node_modules for skills
├── source-parser.ts # Parse git URLs, GitHub shorthand, local paths
├── git.ts # Git clone operations
├── telemetry.ts # Anonymous usage tracking
├── types.ts # TypeScript types
├── mintlify.ts # Mintlify skill fetching (legacy)
├── plugin-manifest.ts # Plugin manifest discovery support
├── prompts/ # Interactive prompt helpers
│ └── search-multiselect.ts
├── providers/ # Remote skill providers (GitHub, HuggingFace, Mintlify)
│ ├── index.ts
│ ├── registry.ts
│ ├── types.ts
│ ├── huggingface.ts
│ ├── mintlify.ts
│ └── wellknown.ts
├── init.test.ts # Init command tests
└── test-utils.ts # Test utilities
tests/
├── cross-platform-paths.test.ts # Path normalization across platforms
├── full-depth-discovery.test.ts # --full-depth skill discovery tests
├── openclaw-paths.test.ts # OpenClaw-specific path tests
├── plugin-manifest-discovery.test.ts # Plugin manifest skill discovery
├── sanitize-name.test.ts # Tests for sanitizeName (path traversal prevention)
├── skill-matching.test.ts # Tests for filterSkills (multi-word skill name matching)
├── source-parser.test.ts # Tests for URL/path parsing
├── installer-symlink.test.ts # Tests for symlink installation
├── list-installed.test.ts # Tests for listing installed skills
├── skill-path.test.ts # Tests for skill path handling
├── wellknown-provider.test.ts # Tests for well-known provider
├── xdg-config-paths.test.ts # XDG global path handling tests
└── dist.test.ts # Tests for built distribution
```
## Update Checking System
### How `skills check` and `skills update` Work
1. Read `~/.agents/.skill-lock.json` for installed skills
2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath`
3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`. Optional auth token is sourced from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` to improve rate limits.
4. `fetchSkillFolderHash` calls GitHub Trees API directly (`/git/trees/<branch>?recursive=1` for `main`, then `master` fallback)
5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available
6. `skills update` reinstalls changed skills by invoking the current CLI entrypoint directly (`node <repo>/bin/cli.mjs add <source-tree-url> -g -y`) to avoid nested npm exec/npx behavior
### Lock File Compatibility
The lock file format is v3. Key field: `skillFolderHash` (GitHub tree SHA for the skill folder).
If reading an older lock file version, it's wiped. Users must reinstall skills to populate the new format.
## Key Integration Points
| Feature | Implementation |
| -------------------------- | ------------------------------------------------------------- |
| `skills add` | `src/add.ts` - full implementation |
| `skills experimental_sync` | `src/sync.ts` - crawl node_modules |
| `skills check` | `src/cli.ts` + `fetchSkillFolderHash` in `src/skill-lock.ts` |
| `skills update` | `src/cli.ts` direct hash compare + reinstall via `skills add` |
## Development
```bash
# Install dependencies
pnpm install
# Build
pnpm build
# Test locally
pnpm dev add vercel-labs/agent-skills --list
pnpm dev experimental_sync
pnpm dev check
pnpm dev update
pnpm dev init my-skill
# Run all tests
pnpm test
# Run specific test file(s)
pnpm test tests/sanitize-name.test.ts
pnpm test tests/skill-matching.test.ts tests/source-parser.test.ts
# Type check
pnpm type-check
# Format code
pnpm format
# Check formatting
pnpm format:check
# Validate and sync agent metadata/docs
pnpm run -C scripts validate-agents.ts
pnpm run -C scripts sync-agents.ts
```
## Code Style
This project uses Prettier for code formatting. **Always run `pnpm format` before committing changes** to ensure consistent formatting.
```bash
# Format all files
pnpm format
# Check formatting without fixing
pnpm format:check
```
CI will fail if code is not properly formatted.
## Publishing
```bash
# 1. Bump version in package.json
# 2. Build
pnpm build
# 3. Publish
npm publish
```
## Adding a New Agent
1. Add the agent definition to `src/agents.ts`
2. Run `pnpm run -C scripts validate-agents.ts` to validate
3. Run `pnpm run -C scripts sync-agents.ts` to update README.md and package keywords
================================================
FILE: README.md
================================================
# skills
The CLI for the open agent skills ecosystem.
<!-- agent-list:start -->
Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [39 more](#available-agents).
<!-- agent-list:end -->
## Install a Skill
```bash
npx skills add vercel-labs/agent-skills
```
### Source Formats
```bash
# GitHub shorthand (owner/repo)
npx skills add vercel-labs/agent-skills
# Full GitHub URL
npx skills add https://github.com/vercel-labs/agent-skills
# Direct path to a skill in a repo
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# GitLab URL
npx skills add https://gitlab.com/org/repo
# Any git URL
npx skills add git@github.com:vercel-labs/agent-skills.git
# Local path
npx skills add ./my-local-skills
```
### Options
| Option | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-g, --global` | Install to user directory instead of project |
| `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Available Agents](#available-agents)<!-- agent-names:end --> |
| `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills) |
| `-l, --list` | List available skills without installing |
| `--copy` | Copy files instead of symlinking to agent directories |
| `-y, --yes` | Skip all confirmation prompts |
| `--all` | Install all skills to all agents without prompts |
### Examples
```bash
# List skills in a repository
npx skills add vercel-labs/agent-skills --list
# Install specific skills
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
# Install a skill with spaces in the name (must be quoted)
npx skills add owner/repo --skill "Convex Best Practices"
# Install to specific agents
npx skills add vercel-labs/agent-skills -a claude-code -a opencode
# Non-interactive installation (CI/CD friendly)
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
# Install all skills from a repo to all agents
npx skills add vercel-labs/agent-skills --all
# Install all skills to specific agents
npx skills add vercel-labs/agent-skills --skill '*' -a claude-code
# Install specific skills to all agents
npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
```
### Installation Scope
| Scope | Flag | Location | Use Case |
| ----------- | --------- | ------------------- | --------------------------------------------- |
| **Project** | (default) | `./<agent>/skills/` | Committed with your project, shared with team |
| **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
### Installation Methods
When installing interactively, you can choose:
| Method | Description |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| **Symlink** (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
| **Copy** | Creates independent copies for each agent. Use when symlinks aren't supported. |
## Other Commands
| Command | Description |
| ---------------------------- | ---------------------------------------------- |
| `npx skills list` | List installed skills (alias: `ls`) |
| `npx skills find [query]` | Search for skills interactively or by keyword |
| `npx skills remove [skills]` | Remove installed skills from agents |
| `npx skills check` | Check for available skill updates |
| `npx skills update` | Update all installed skills to latest versions |
| `npx skills init [name]` | Create a new SKILL.md template |
### `skills list`
List all installed skills. Similar to `npm ls`.
```bash
# List all installed skills (project and global)
npx skills list
# List only global skills
npx skills ls -g
# Filter by specific agents
npx skills ls -a claude-code -a cursor
```
### `skills find`
Search for skills interactively or by keyword.
```bash
# Interactive search (fzf-style)
npx skills find
# Search by keyword
npx skills find typescript
```
### `skills check` / `skills update`
```bash
# Check if any installed skills have updates
npx skills check
# Update all skills to latest versions
npx skills update
```
### `skills init`
```bash
# Create SKILL.md in current directory
npx skills init
# Create a new skill in a subdirectory
npx skills init my-skill
```
### `skills remove`
Remove installed skills from agents.
```bash
# Remove interactively (select from installed skills)
npx skills remove
# Remove specific skill by name
npx skills remove web-design-guidelines
# Remove multiple skills
npx skills remove frontend-design web-design-guidelines
# Remove from global scope
npx skills remove --global web-design-guidelines
# Remove from specific agents only
npx skills remove --agent claude-code cursor my-skill
# Remove all installed skills without confirmation
npx skills remove --all
# Remove all skills from a specific agent
npx skills remove --skill '*' -a cursor
# Remove a specific skill from all agents
npx skills remove my-skill --agent '*'
# Use 'rm' alias
npx skills rm my-skill
```
| Option | Description |
| -------------- | ------------------------------------------------ |
| `-g, --global` | Remove from global scope (~/) instead of project |
| `-a, --agent` | Remove from specific agents (use `'*'` for all) |
| `-s, --skill` | Specify skills to remove (use `'*'` for all) |
| `-y, --yes` | Skip confirmation prompts |
| `--all` | Shorthand for `--skill '*' --agent '*' -y` |
## What are Agent Skills?
Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md`
files with YAML frontmatter containing a `name` and `description`.
Skills let agents perform specialized tasks like:
- Generating release notes from git history
- Creating PRs following your team's conventions
- Integrating with external tools (Linear, Notion, etc.)
Discover skills at **[skills.sh](https://skills.sh)**
## Supported Agents
Skills can be installed to any of these agents:
<!-- supported-agents:start -->
| Agent | `--agent` | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
| Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
| Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
| Cline, Warp | `cline`, `warp` | `.agents/skills/` | `~/.agents/skills/` |
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
| Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
| Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
| Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Zencoder | `zencoder` | `.zencoder/skills/` | `~/.zencoder/skills/` |
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
<!-- supported-agents:end -->
> [!NOTE]
> **Kiro CLI users:** After installing skills, manually add them to your custom agent's `resources` in
> `.kiro/agents/<agent>.json`:
>
> ```json
> {
> "resources": ["skill://.kiro/skills/**/SKILL.md"]
> }
> ```
The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select
which agents to install to.
## Creating Skills
Skills are directories containing a `SKILL.md` file with YAML frontmatter:
```markdown
---
name: my-skill
description: What this skill does and when to use it
---
# My Skill
Instructions for the agent to follow when this skill is activated.
## When to Use
Describe the scenarios where this skill should be used.
## Steps
1. First, do this
2. Then, do that
```
### Required Fields
- `name`: Unique identifier (lowercase, hyphens allowed)
- `description`: Brief explanation of what the skill does
### Optional Fields
- `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
internal tooling.
```markdown
---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
internal: true
---
```
### Skill Discovery
The CLI searches for skills in these locations within a repository:
<!-- skill-discovery:start -->
- Root directory (if it contains `SKILL.md`)
- `skills/`
- `skills/.curated/`
- `skills/.experimental/`
- `skills/.system/`
- `.agents/skills/`
- `.augment/skills/`
- `.claude/skills/`
- `./skills/`
- `.codebuddy/skills/`
- `.commandcode/skills/`
- `.continue/skills/`
- `.cortex/skills/`
- `.crush/skills/`
- `.factory/skills/`
- `.goose/skills/`
- `.junie/skills/`
- `.iflow/skills/`
- `.kilocode/skills/`
- `.kiro/skills/`
- `.kode/skills/`
- `.mcpjam/skills/`
- `.vibe/skills/`
- `.mux/skills/`
- `.openhands/skills/`
- `.pi/skills/`
- `.qoder/skills/`
- `.qwen/skills/`
- `.roo/skills/`
- `.trae/skills/`
- `.windsurf/skills/`
- `.zencoder/skills/`
- `.neovate/skills/`
- `.pochi/skills/`
- `.adal/skills/`
<!-- skill-discovery:end -->
### Plugin Manifest Discovery
If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered:
```json
// .claude-plugin/marketplace.json
{
"metadata": { "pluginRoot": "./plugins" },
"plugins": [
{
"name": "my-plugin",
"source": "my-plugin",
"skills": ["./skills/review", "./skills/test"]
}
]
}
```
This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
If no skills are found in standard locations, a recursive search is performed.
## Compatibility
Skills are generally compatible across agents since they follow a
shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
| Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | OpenClaw | Neovate | Pi | Qoder | Zencoder |
| --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- |
| Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| `allowed-tools` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
| `context: fork` | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
| Hooks | No | No | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
## Troubleshooting
### "No skills found"
Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
### Skill not loading in agent
- Verify the skill was installed to the correct path
- Check the agent's documentation for skill loading requirements
- Ensure the `SKILL.md` frontmatter is valid YAML
### Permission errors
Ensure you have write access to the target directory.
## Environment Variables
| Variable | Description |
| ------------------------- | -------------------------------------------------------------------------- |
| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
| `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
```bash
# Install internal skills
INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
```
## Telemetry
This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
Telemetry is automatically disabled in CI environments.
## Related Links
- [Agent Skills Specification](https://agentskills.io)
- [Skills Directory](https://skills.sh)
- [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
- [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
- [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
- [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills)
- [Cline Skills Documentation](https://docs.cline.bot/features/skills)
- [CodeBuddy Skills Documentation](https://www.codebuddy.ai/docs/ide/Features/Skills)
- [Codex Skills Documentation](https://developers.openai.com/codex/skills)
- [Command Code Skills Documentation](https://commandcode.ai/docs/skills)
- [Crush Skills Documentation](https://github.com/charmbracelet/crush?tab=readme-ov-file#agent-skills)
- [Cursor Skills Documentation](https://cursor.com/docs/context/skills)
- [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/)
- [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
- [iFlow CLI Skills Documentation](https://platform.iflow.cn/en/cli/examples/skill)
- [Kimi Code CLI Skills Documentation](https://moonshotai.github.io/kimi-cli/en/customization/skills.html)
- [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
- [Kode Skills Documentation](https://github.com/shareAI-lab/kode/blob/main/docs/skills.md)
- [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
- [Qwen Code Skills Documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)
- [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills)
- [Pi Skills Documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
- [Qoder Skills Documentation](https://docs.qoder.com/cli/Skills)
- [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
- [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
- [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
- [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
## License
MIT
================================================
FILE: ThirdPartyNoticeText.txt
================================================
/*!----------------- Skills CLI ThirdPartyNotices -------------------------------------------------------
The Skills CLI incorporates third party material from the projects listed below.
The original copyright notice and the license under which this material was received
are set forth below. These licenses and notices are provided for informational purposes only.
---------------------------------------------
Third Party Code Components
--------------------------------------------
================================================================================
Package: @clack/core@0.4.1
License: MIT
Repository: https://github.com/natemoo-re/clack
--------------------------------------------------------------------------------
MIT License
Copyright (c) Nate Moore
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
================================================================================
Package: @clack/prompts@0.11.0
License: MIT
Repository: https://github.com/bombshell-dev/clack
--------------------------------------------------------------------------------
MIT License
Copyright (c) Nate Moore
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
================================================================================
Package: gray-matter@4.0.3
License: MIT
Repository: https://github.com/jonschlinkert/gray-matter
--------------------------------------------------------------------------------
The MIT License (MIT)
Copyright (c) 2014-2018, Jon Schlinkert.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================================================
Package: picocolors@1.1.1
License: ISC
Repository: https://github.com/alexeyraspopov/picocolors
--------------------------------------------------------------------------------
ISC License
Copyright (c) 2021-2024 Oleksii Raspopov, Kostiantyn Denysov, Anton Verinov
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
================================================================================
Package: simple-git@3.30.0
License: MIT
Repository: https://github.com/steveukx/git-js
--------------------------------------------------------------------------------
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================================================
Package: sisteransi@1.0.5
License: MIT
Repository: https://github.com/terkelg/sisteransi
--------------------------------------------------------------------------------
MIT License
Copyright (c) 2018 Terkel Gjervig Nielsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================================================
Package: xdg-basedir@5.1.0
License: MIT
Repository: https://github.com/sindresorhus/xdg-basedir
--------------------------------------------------------------------------------
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
================================================================================
*/
================================================
FILE: bin/cli.mjs
================================================
#!/usr/bin/env node
import module from 'node:module';
// https://nodejs.org/api/module.html#module-compile-cache
if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
try {
module.enableCompileCache();
} catch {
// Ignore errors
}
}
await import('../dist/cli.mjs');
================================================
FILE: build.config.mjs
================================================
import { defineBuildConfig } from 'obuild/config';
// https://github.com/unjs/obuild
export default defineBuildConfig({
entries: [{ type: 'bundle', input: './src/cli.ts' }],
});
================================================
FILE: package.json
================================================
{
"name": "skills",
"version": "1.4.5",
"description": "The open agent skills ecosystem",
"type": "module",
"bin": {
"skills": "./bin/cli.mjs",
"add-skill": "./bin/cli.mjs"
},
"files": [
"dist",
"bin",
"README.md",
"ThirdPartyNoticeText.txt"
],
"scripts": {
"build": "node scripts/generate-licenses.ts && obuild",
"generate-licenses": "node scripts/generate-licenses.ts",
"dev": "node src/cli.ts",
"exec:test": "node scripts/execute-tests.ts",
"prepublishOnly": "npm run build",
"format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\"",
"format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\"",
"prepare": "husky",
"test": "vitest",
"type-check": "tsc --noEmit",
"publish:snapshot": "npm version prerelease --preid=snapshot --no-git-tag-version && npm publish --tag snapshot"
},
"lint-staged": {
"src/**/*.ts": "prettier --write",
"scripts/**/*.ts": "prettier --write",
"tests/**/*.ts": "prettier --write"
},
"keywords": [
"cli",
"agent-skills",
"skills",
"ai-agents",
"amp",
"antigravity",
"augment",
"claude-code",
"openclaw",
"cline",
"codebuddy",
"codex",
"command-code",
"continue",
"cortex",
"crush",
"cursor",
"deepagents",
"droid",
"gemini-cli",
"github-copilot",
"goose",
"junie",
"iflow-cli",
"kilo",
"kimi-cli",
"kiro-cli",
"kode",
"mcpjam",
"mistral-vibe",
"mux",
"opencode",
"openhands",
"pi",
"qoder",
"qwen-code",
"replit",
"roo",
"trae",
"trae-cn",
"warp",
"windsurf",
"zencoder",
"neovate",
"pochi",
"adal",
"universal"
],
"repository": {
"type": "git",
"url": "git+https://github.com/vercel-labs/skills.git"
},
"homepage": "https://github.com/vercel-labs/skills#readme",
"bugs": {
"url": "https://github.com/vercel-labs/skills/issues"
},
"author": "",
"license": "MIT",
"devDependencies": {
"@clack/prompts": "^0.11.0",
"@types/bun": "latest",
"@types/node": "^22.10.0",
"gray-matter": "^4.0.3",
"husky": "^9.1.7",
"lint-staged": "^16.2.7",
"obuild": "^0.4.22",
"picocolors": "^1.1.1",
"prettier": "^3.8.1",
"simple-git": "^3.27.0",
"typescript": "^5.9.3",
"vitest": "^4.0.17",
"xdg-basedir": "^5.1.0"
},
"engines": {
"node": ">=18"
},
"packageManager": "pnpm@10.17.1"
}
================================================
FILE: scripts/execute-tests.ts
================================================
#!/usr/bin/env node
import { spawn } from 'node:child_process';
import { readdir } from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { fileURLToPath } from 'node:url';
type RunOptions = {
rootDir: string;
testsDir: string;
filter?: RegExp;
listOnly: boolean;
};
function parseArgs(argv: string[], rootDir: string): RunOptions {
const testsDir = path.join(rootDir, 'tests');
let filter: RegExp | undefined;
let listOnly = false;
for (let i = 0; i < argv.length; i++) {
const arg = argv[i];
if (arg === '--list' || arg === '-l') {
listOnly = true;
continue;
}
if (arg === '--filter' || arg === '-f') {
const pattern = argv[i + 1];
if (!pattern) throw new Error('Missing value for --filter');
filter = new RegExp(pattern);
i++;
continue;
}
if (arg === '--help' || arg === '-h') {
console.log(
`Usage: node scripts/execute-tests.ts [options]\n\nOptions:\n -l, --list List discovered test files and exit\n -f, --filter <regex> Only run tests whose path matches regex\n -h, --help Show help\n`
);
process.exit(0);
}
throw new Error(`Unknown argument: ${arg}`);
}
return { rootDir, testsDir, filter, listOnly };
}
async function findTestFiles(dir: string): Promise<string[]> {
const entries = await readdir(dir, { withFileTypes: true });
const files: string[] = [];
for (const entry of entries) {
const fullPath = path.join(dir, entry.name);
if (entry.isDirectory()) {
files.push(...(await findTestFiles(fullPath)));
continue;
}
if (entry.isFile() && entry.name.endsWith('.test.ts')) {
files.push(fullPath);
}
}
return files.sort((a, b) => a.localeCompare(b));
}
async function runOneTest(rootDir: string, testFile: string): Promise<number> {
return await new Promise((resolve, reject) => {
const child = spawn('node', [testFile], {
cwd: rootDir,
stdio: 'inherit',
});
child.on('error', reject);
child.on('exit', (code) => resolve(code ?? 1));
});
}
async function main(): Promise<void> {
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(scriptDir, '..');
const opts = parseArgs(process.argv.slice(2), rootDir);
let testFiles: string[];
try {
testFiles = await findTestFiles(opts.testsDir);
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
process.exit(1);
}
if (opts.filter) {
testFiles = testFiles.filter((f) => opts.filter!.test(f));
}
if (testFiles.length === 0) {
process.exit(1);
}
if (opts.listOnly) {
for (const file of testFiles) console.log(path.relative(opts.rootDir, file));
return;
}
let failed = 0;
for (const testFile of testFiles) {
console.log(`\n— Running ${path.relative(opts.rootDir, testFile)} —`);
const exitCode = await runOneTest(opts.rootDir, testFile);
if (exitCode !== 0) failed++;
}
if (failed > 0) {
process.exit(1);
}
console.log(`\nAll ${testFiles.length} test file(s) passed.`);
}
await main();
================================================
FILE: scripts/generate-licenses.ts
================================================
#!/usr/bin/env node
/**
* Generates ThirdPartyNoticeText.txt for bundled dependencies.
* Run during build to ensure license compliance.
*/
import { execSync } from 'child_process';
import { writeFileSync, readFileSync, existsSync } from 'fs';
import { join } from 'path';
// Dependencies that get bundled into the CLI
const BUNDLED_PACKAGES = [
'@clack/prompts',
'@clack/core',
'picocolors',
'gray-matter',
'simple-git',
'xdg-basedir',
'sisteransi',
'is-unicode-supported',
];
interface LicenseInfo {
licenses: string;
repository?: string;
publisher?: string;
licenseFile?: string;
}
function getLicenseText(pkgPath: string): string {
const possibleFiles = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'license', 'license.md'];
for (const file of possibleFiles) {
const filePath = join(pkgPath, file);
if (existsSync(filePath)) {
return readFileSync(filePath, 'utf-8').trim();
}
}
return '';
}
function main() {
console.log('Generating ThirdPartyNoticeText.txt...');
// Get license info from license-checker
const output = execSync('npx license-checker --json', { encoding: 'utf-8' });
const allLicenses: Record<string, LicenseInfo> = JSON.parse(output);
const lines: string[] = [
'/*!----------------- Skills CLI ThirdPartyNotices -------------------------------------------------------',
'',
'The Skills CLI incorporates third party material from the projects listed below.',
'The original copyright notice and the license under which this material was received',
'are set forth below. These licenses and notices are provided for informational purposes only.',
'',
'---------------------------------------------',
'Third Party Code Components',
'--------------------------------------------',
'',
];
for (const [pkgNameVersion, info] of Object.entries(allLicenses)) {
// Extract package name (remove version)
const pkgName = pkgNameVersion.replace(/@[\d.]+(-.*)?$/, '').replace(/^(.+)@.*$/, '$1');
// Check if this is a bundled package
const isBundled = BUNDLED_PACKAGES.some(
(bundled) => pkgName === bundled || pkgNameVersion.startsWith(bundled + '@')
);
if (!isBundled) continue;
// Get the actual license text from the package
const pkgPath = join(process.cwd(), 'node_modules', pkgName);
const licenseText = getLicenseText(pkgPath);
lines.push('='.repeat(80));
lines.push(`Package: ${pkgNameVersion}`);
lines.push(`License: ${info.licenses}`);
if (info.repository) {
lines.push(`Repository: ${info.repository}`);
}
lines.push('-'.repeat(80));
lines.push('');
if (licenseText) {
lines.push(licenseText);
} else {
// Fallback to generic MIT/ISC text
if (info.licenses === 'MIT') {
lines.push('MIT License');
lines.push('');
lines.push('Permission is hereby granted, free of charge, to any person obtaining a copy');
lines.push('of this software and associated documentation files (the "Software"), to deal');
lines.push('in the Software without restriction, including without limitation the rights');
lines.push('to use, copy, modify, merge, publish, distribute, sublicense, and/or sell');
lines.push('copies of the Software, and to permit persons to whom the Software is');
lines.push('furnished to do so, subject to the following conditions:');
lines.push('');
lines.push(
'The above copyright notice and this permission notice shall be included in all'
);
lines.push('copies or substantial portions of the Software.');
lines.push('');
lines.push('THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR');
lines.push('IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,');
lines.push('FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE');
lines.push('AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER');
lines.push('LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,');
lines.push('OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE');
lines.push('SOFTWARE.');
} else if (info.licenses === 'ISC') {
lines.push('ISC License');
lines.push('');
lines.push('Permission to use, copy, modify, and/or distribute this software for any');
lines.push('purpose with or without fee is hereby granted, provided that the above');
lines.push('copyright notice and this permission notice appear in all copies.');
lines.push('');
lines.push('THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES');
lines.push('WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF');
lines.push('MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR');
lines.push('ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES');
lines.push('WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN');
lines.push('ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF');
lines.push('OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.');
}
}
lines.push('');
lines.push('');
}
lines.push('='.repeat(80));
lines.push('*/');
const content = lines.join('\n');
writeFileSync('ThirdPartyNoticeText.txt', content);
console.log('Generated ThirdPartyNoticeText.txt');
}
main();
================================================
FILE: scripts/sync-agents.ts
================================================
#!/usr/bin/env node
import { readFileSync, writeFileSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';
import { agents } from '../src/agents.ts';
const ROOT = join(import.meta.dirname, '..');
const README_PATH = join(ROOT, 'README.md');
const PACKAGE_PATH = join(ROOT, 'package.json');
function generateAgentList(): string {
const agentList = Object.values(agents);
const count = agentList.length;
return `Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [${count - 4} more](#available-agents).`;
}
function generateAgentNames(): string {
return 'Target specific agents (e.g., `claude-code`, `codex`). See [Available Agents](#available-agents)';
}
function generateAvailableAgentsTable(): string {
// Group agents by their paths
const pathGroups = new Map<
string,
{
keys: string[];
displayNames: string[];
skillsDir: string;
globalSkillsDir: string | undefined;
}
>();
for (const [key, a] of Object.entries(agents)) {
const pathKey = `${a.skillsDir}|${a.globalSkillsDir}`;
if (!pathGroups.has(pathKey)) {
pathGroups.set(pathKey, {
keys: [],
displayNames: [],
skillsDir: a.skillsDir,
globalSkillsDir: a.globalSkillsDir,
});
}
const group = pathGroups.get(pathKey)!;
group.keys.push(key);
group.displayNames.push(a.displayName);
}
const rows = Array.from(pathGroups.values()).map((group) => {
const globalPath = group.globalSkillsDir
? `\`${group.globalSkillsDir.replace(homedir(), '~')}/\``
: 'N/A (project-only)';
const names = group.displayNames.join(', ');
const keys = group.keys.map((k) => `\`${k}\``).join(', ');
return `| ${names} | ${keys} | \`${group.skillsDir}/\` | ${globalPath} |`;
});
return [
'| Agent | `--agent` | Project Path | Global Path |',
'|-------|-----------|--------------|-------------|',
...rows,
].join('\n');
}
function generateSkillDiscoveryPaths(): string {
const standardPaths = [
'- Root directory (if it contains `SKILL.md`)',
'- `skills/`',
'- `skills/.curated/`',
'- `skills/.experimental/`',
'- `skills/.system/`',
];
const agentPaths = [...new Set(Object.values(agents).map((a) => a.skillsDir))].map(
(p) => `- \`.${p.startsWith('.') ? p.slice(1) : '/' + p}/\``
);
return [...standardPaths, ...agentPaths].join('\n');
}
function generateKeywords(): string[] {
const baseKeywords = ['cli', 'agent-skills', 'skills', 'ai-agents'];
const agentKeywords = Object.keys(agents);
return [...baseKeywords, ...agentKeywords];
}
function replaceSection(
content: string,
marker: string,
replacement: string,
inline = false
): string {
const regex = new RegExp(`(<!-- ${marker}:start -->)[\\s\\S]*?(<!-- ${marker}:end -->)`, 'g');
if (inline) {
return content.replace(regex, `$1${replacement}$2`);
}
return content.replace(regex, `$1\n${replacement}\n$2`);
}
function main() {
let readme = readFileSync(README_PATH, 'utf-8');
readme = replaceSection(readme, 'agent-list', generateAgentList());
readme = replaceSection(readme, 'agent-names', generateAgentNames(), true);
readme = replaceSection(readme, 'supported-agents', generateAvailableAgentsTable());
readme = replaceSection(readme, 'skill-discovery', generateSkillDiscoveryPaths());
writeFileSync(README_PATH, readme);
console.log('README.md updated');
const pkg = JSON.parse(readFileSync(PACKAGE_PATH, 'utf-8'));
pkg.keywords = generateKeywords();
writeFileSync(PACKAGE_PATH, JSON.stringify(pkg, null, 2) + '\n');
console.log('package.json updated');
}
main();
================================================
FILE: scripts/validate-agents.ts
================================================
#!/usr/bin/env node
import { homedir } from 'os';
import { agents } from '../src/agents.ts';
let hasErrors = false;
function error(message: string) {
console.error(message);
hasErrors = true;
}
/**
* Checks for duplicate `displayName` values among the agents.
*
* Iterates through the `agents` object, collecting all `displayName` values (case-insensitive)
* and mapping them to their corresponding agent keys. If any `displayName` is associated with
* more than one agent, an error is reported listing the duplicate names and their keys.
*
* @throws Will call the `error` function if duplicate display names are found.
*/
function checkDuplicateDisplayNames() {
const displayNames = new Map<string, string[]>();
for (const [key, config] of Object.entries(agents)) {
const name = config.displayName.toLowerCase();
if (!displayNames.has(name)) {
displayNames.set(name, []);
}
displayNames.get(name)!.push(key);
}
for (const [name, keys] of displayNames) {
if (keys.length > 1) {
error(`Duplicate displayName "${name}" found in agents: ${keys.join(', ')}`);
}
}
}
/**
* Checks for duplicate `skillsDir` and `globalSkillsDir` values among agents.
*
* Iterates through the `agents` object, collecting all `skillsDir` and normalized `globalSkillsDir`
* paths. If any directory is associated with more than one agent, an error is reported listing the
* conflicting agents.
*
* @remarks
* - The `globalSkillsDir` path is normalized by replacing the user's home directory with `~`.
* - Errors are reported using the `error` function.
*
* @throws Will call `error` if duplicate directories are found.
*/
function checkDuplicateSkillsDirs() {
const skillsDirs = new Map<string, string[]>();
const globalSkillsDirs = new Map<string, string[]>();
for (const [key, config] of Object.entries(agents)) {
if (!skillsDirs.has(config.skillsDir)) {
skillsDirs.set(config.skillsDir, []);
}
skillsDirs.get(config.skillsDir)!.push(key);
const globalPath = config.globalSkillsDir?.replace(homedir(), '~');
if (globalPath) {
if (!globalSkillsDirs.has(globalPath)) {
globalSkillsDirs.set(globalPath, []);
}
globalSkillsDirs.get(globalPath)!.push(key);
}
}
for (const [dir, keys] of skillsDirs) {
if (keys.length > 1) {
error(`Duplicate skillsDir "${dir}" found in agents: ${keys.join(', ')}`);
}
}
for (const [dir, keys] of globalSkillsDirs) {
if (keys.length > 1) {
error(`Duplicate globalSkillsDir "${dir}" found in agents: ${keys.join(', ')}`);
}
}
}
console.log('Validating agents...\n');
checkDuplicateDisplayNames();
// It's fine to have duplicate skills dirs
// checkDuplicateSkillsDirs();
if (hasErrors) {
console.log('\nValidation failed.');
process.exit(1);
} else {
console.log('All agents valid.');
}
================================================
FILE: skills/find-skills/SKILL.md
================================================
---
name: find-skills
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
---
# Find Skills
This skill helps you discover and install skills from the open agent skills ecosystem.
## When to Use This Skill
Use this skill when the user:
- Asks "how do I do X" where X might be a common task with an existing skill
- Says "find a skill for X" or "is there a skill for X"
- Asks "can you do X" where X is a specialized capability
- Expresses interest in extending agent capabilities
- Wants to search for tools, templates, or workflows
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
## What is the Skills CLI?
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
**Key commands:**
- `npx skills find [query]` - Search for skills interactively or by keyword
- `npx skills add <package>` - Install a skill from GitHub or other sources
- `npx skills check` - Check for skill updates
- `npx skills update` - Update all installed skills
**Browse skills at:** https://skills.sh/
## How to Help Users Find Skills
### Step 1: Understand What They Need
When a user asks for help with something, identify:
1. The domain (e.g., React, testing, design, deployment)
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
3. Whether this is a common enough task that a skill likely exists
### Step 2: Check the Leaderboard First
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
For example, top skills for web development include:
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
### Step 3: Search for Skills
If the leaderboard doesn't cover the user's need, run the find command:
```bash
npx skills find [query]
```
For example:
- User asks "how do I make my React app faster?" → `npx skills find react performance`
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
- User asks "I need to create a changelog" → `npx skills find changelog`
### Step 4: Verify Quality Before Recommending
**Do not recommend a skill based solely on search results.** Always verify:
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
### Step 5: Present Options to the User
When you find relevant skills, present them to the user with:
1. The skill name and what it does
2. The install count and source
3. The install command they can run
4. A link to learn more at skills.sh
Example response:
```
I found a skill that might help! The "react-best-practices" skill provides
React and Next.js performance optimization guidelines from Vercel Engineering.
(185K installs)
To install it:
npx skills add vercel-labs/agent-skills@react-best-practices
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
```
### Step 6: Offer to Install
If the user wants to proceed, you can install the skill for them:
```bash
npx skills add <owner/repo@skill> -g -y
```
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
## Common Skill Categories
When searching, consider these common categories:
| Category | Example Queries |
| --------------- | ---------------------------------------- |
| Web Development | react, nextjs, typescript, css, tailwind |
| Testing | testing, jest, playwright, e2e |
| DevOps | deploy, docker, kubernetes, ci-cd |
| Documentation | docs, readme, changelog, api-docs |
| Code Quality | review, lint, refactor, best-practices |
| Design | ui, ux, design-system, accessibility |
| Productivity | workflow, automation, git |
## Tips for Effective Searches
1. **Use specific keywords**: "react testing" is better than just "testing"
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
## When No Skills Are Found
If no relevant skills exist:
1. Acknowledge that no existing skill was found
2. Offer to help with the task directly using your general capabilities
3. Suggest the user could create their own skill with `npx skills init`
Example:
```
I searched for skills related to "xyz" but didn't find any matches.
I can still help you with this task directly! Would you like me to proceed?
If this is something you do often, you could create your own skill:
npx skills init my-xyz-skill
```
================================================
FILE: src/add-prompt.test.ts
================================================
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { promptForAgents } from './add.js';
import * as skillLock from './skill-lock.js';
import * as searchMultiselectModule from './prompts/search-multiselect.js';
// Mock dependencies
vi.mock('./skill-lock.js');
vi.mock('./prompts/search-multiselect.js');
vi.mock('./telemetry.js', () => ({
setVersion: vi.fn(),
track: vi.fn(),
}));
vi.mock('../package.json', () => ({
default: { version: '1.0.0' },
}));
describe('promptForAgents', () => {
// Cast to any to avoid AgentType validation in tests
const choices: any[] = [
{ value: 'opencode', label: 'OpenCode' },
{ value: 'cursor', label: 'Cursor' },
{ value: 'claude-code', label: 'Claude Code' },
];
beforeEach(() => {
vi.clearAllMocks();
});
it('should use default agents (claude-code, opencode, codex) when no history exists', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(undefined);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(['opencode']);
await promptForAgents('Select agents', choices);
// Should default to claude-code, opencode, codex (filtered by available choices)
expect(searchMultiselectModule.searchMultiselect).toHaveBeenCalledWith(
expect.objectContaining({
initialSelected: ['claude-code', 'opencode'],
})
);
});
it('should use last selected agents when history exists', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(['cursor']);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(['cursor']);
await promptForAgents('Select agents', choices);
expect(searchMultiselectModule.searchMultiselect).toHaveBeenCalledWith(
expect.objectContaining({
initialSelected: ['cursor'],
})
);
});
it('should filter out invalid agents from history', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(['cursor', 'invalid-agent']);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(['cursor']);
await promptForAgents('Select agents', choices);
expect(searchMultiselectModule.searchMultiselect).toHaveBeenCalledWith(
expect.objectContaining({
initialSelected: ['cursor'],
})
);
});
it('should use default agents if all history agents are invalid', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(['invalid-agent']);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(['opencode']);
await promptForAgents('Select agents', choices);
// When history is invalid, should fall back to defaults (claude-code, opencode, codex)
// filtered by available choices
expect(searchMultiselectModule.searchMultiselect).toHaveBeenCalledWith(
expect.objectContaining({
initialSelected: ['claude-code', 'opencode'],
})
);
});
it('should save selected agents if not cancelled', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(undefined);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(['opencode']);
await promptForAgents('Select agents', choices);
expect(skillLock.saveSelectedAgents).toHaveBeenCalledWith(['opencode']);
});
it('should not save agents if cancelled', async () => {
vi.mocked(skillLock.getLastSelectedAgents).mockResolvedValue(undefined);
vi.mocked(searchMultiselectModule.searchMultiselect).mockResolvedValue(
searchMultiselectModule.cancelSymbol
);
await promptForAgents('Select agents', choices);
expect(skillLock.saveSelectedAgents).not.toHaveBeenCalled();
});
});
================================================
FILE: src/add.test.ts
================================================
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, rmSync, mkdirSync, writeFileSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
import { runCli } from './test-utils.ts';
import { shouldInstallInternalSkills } from './skills.ts';
import { parseAddOptions } from './add.ts';
describe('add command', () => {
let testDir: string;
beforeEach(() => {
testDir = join(tmpdir(), `skills-add-test-${Date.now()}`);
mkdirSync(testDir, { recursive: true });
});
afterEach(() => {
if (existsSync(testDir)) {
rmSync(testDir, { recursive: true, force: true });
}
});
it('should show error when no source provided', () => {
const result = runCli(['add'], testDir);
expect(result.stdout).toContain('ERROR');
expect(result.stdout).toContain('Missing required argument: source');
expect(result.exitCode).toBe(1);
});
it('should show error for non-existent local path', () => {
const result = runCli(['add', './non-existent-path', '-y'], testDir);
expect(result.stdout).toContain('Local path does not exist');
expect(result.exitCode).toBe(1);
});
it('should list skills from local path with --list flag', () => {
// Create a test skill
const skillDir = join(testDir, 'test-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: test-skill
description: A test skill for testing
---
# Test Skill
This is a test skill.
`
);
const result = runCli(['add', testDir, '--list'], testDir);
expect(result.stdout).toContain('test-skill');
expect(result.stdout).toContain('A test skill for testing');
expect(result.exitCode).toBe(0);
});
it('should show no skills found for empty directory', () => {
const result = runCli(['add', testDir, '-y'], testDir);
expect(result.stdout).toContain('No skills found');
expect(result.stdout).toContain('No valid skills found');
expect(result.exitCode).toBe(1);
});
it('should install skill from local path with -y flag', () => {
// Create a test skill
const skillDir = join(testDir, 'skills', 'my-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: my-skill
description: My test skill
---
# My Skill
Instructions here.
`
);
// Create a target directory to install to
const targetDir = join(testDir, 'project');
mkdirSync(targetDir, { recursive: true });
const result = runCli(['add', testDir, '-y', '-g', '--agent', 'claude-code'], targetDir);
expect(result.stdout).toContain('my-skill');
expect(result.stdout).toContain('Done!');
expect(result.exitCode).toBe(0);
});
it('should filter skills by name with --skill flag', () => {
// Create multiple test skills
const skill1Dir = join(testDir, 'skills', 'skill-one');
const skill2Dir = join(testDir, 'skills', 'skill-two');
mkdirSync(skill1Dir, { recursive: true });
mkdirSync(skill2Dir, { recursive: true });
writeFileSync(
join(skill1Dir, 'SKILL.md'),
`---
name: skill-one
description: First skill
---
# Skill One
`
);
writeFileSync(
join(skill2Dir, 'SKILL.md'),
`---
name: skill-two
description: Second skill
---
# Skill Two
`
);
const result = runCli(['add', testDir, '--list', '--skill', 'skill-one'], testDir);
// With --list, it should show only the filtered skill info
expect(result.stdout).toContain('skill-one');
});
it('should show error for invalid agent name', () => {
// Create a test skill
const skillDir = join(testDir, 'test-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: test-skill
description: Test
---
# Test
`
);
const result = runCli(['add', testDir, '-y', '--agent', 'invalid-agent'], testDir);
expect(result.stdout).toContain('Invalid agents');
expect(result.exitCode).toBe(1);
});
it('should support add command aliases (a, i, install)', () => {
// Test that aliases work (just check they show missing source error)
const resultA = runCli(['a'], testDir);
const resultI = runCli(['i'], testDir);
const resultInstall = runCli(['install'], testDir);
// All should show the same "missing source" error
expect(resultA.stdout).toContain('Missing required argument: source');
expect(resultI.stdout).toContain('Missing required argument: source');
expect(resultInstall.stdout).toContain('Missing required argument: source');
});
it('should restore from lock file with experimental_install', () => {
const result = runCli(['experimental_install'], testDir);
expect(result.stdout).toContain('No project skills found in skills-lock.json');
});
describe('internal skills', () => {
it('should skip internal skills by default', () => {
// Create an internal skill
const skillDir = join(testDir, 'internal-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: internal-skill
description: An internal skill
metadata:
internal: true
---
# Internal Skill
This is an internal skill.
`
);
const result = runCli(['add', testDir, '--list'], testDir);
expect(result.stdout).not.toContain('internal-skill');
});
it('should show internal skills when INSTALL_INTERNAL_SKILLS=1', () => {
// Create an internal skill
const skillDir = join(testDir, 'internal-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: internal-skill
description: An internal skill
metadata:
internal: true
---
# Internal Skill
This is an internal skill.
`
);
const result = runCli(['add', testDir, '--list'], testDir, {
INSTALL_INTERNAL_SKILLS: '1',
});
expect(result.stdout).toContain('internal-skill');
expect(result.stdout).toContain('An internal skill');
});
it('should show internal skills when INSTALL_INTERNAL_SKILLS=true', () => {
// Create an internal skill
const skillDir = join(testDir, 'internal-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: internal-skill
description: An internal skill
metadata:
internal: true
---
# Internal Skill
This is an internal skill.
`
);
const result = runCli(['add', testDir, '--list'], testDir, {
INSTALL_INTERNAL_SKILLS: 'true',
});
expect(result.stdout).toContain('internal-skill');
});
it('should show non-internal skills alongside internal when env var is set', () => {
// Create both internal and non-internal skills
const internalDir = join(testDir, 'skills', 'internal-skill');
const publicDir = join(testDir, 'skills', 'public-skill');
mkdirSync(internalDir, { recursive: true });
mkdirSync(publicDir, { recursive: true });
writeFileSync(
join(internalDir, 'SKILL.md'),
`---
name: internal-skill
description: An internal skill
metadata:
internal: true
---
# Internal Skill
`
);
writeFileSync(
join(publicDir, 'SKILL.md'),
`---
name: public-skill
description: A public skill
---
# Public Skill
`
);
// Without env var - only public skill visible
const resultWithout = runCli(['add', testDir, '--list'], testDir);
expect(resultWithout.stdout).toContain('public-skill');
expect(resultWithout.stdout).not.toContain('internal-skill');
// With env var - both visible
const resultWith = runCli(['add', testDir, '--list'], testDir, {
INSTALL_INTERNAL_SKILLS: '1',
});
expect(resultWith.stdout).toContain('public-skill');
expect(resultWith.stdout).toContain('internal-skill');
});
it('should not treat metadata.internal: false as internal', () => {
const skillDir = join(testDir, 'not-internal-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: not-internal-skill
description: Explicitly not internal
metadata:
internal: false
---
# Not Internal
`
);
const result = runCli(['add', testDir, '--list'], testDir);
expect(result.stdout).toContain('not-internal-skill');
});
});
});
describe('shouldInstallInternalSkills', () => {
const originalEnv = process.env;
beforeEach(() => {
vi.resetModules();
process.env = { ...originalEnv };
});
afterEach(() => {
process.env = originalEnv;
});
it('should return false when INSTALL_INTERNAL_SKILLS is not set', () => {
delete process.env.INSTALL_INTERNAL_SKILLS;
expect(shouldInstallInternalSkills()).toBe(false);
});
it('should return true when INSTALL_INTERNAL_SKILLS=1', () => {
process.env.INSTALL_INTERNAL_SKILLS = '1';
expect(shouldInstallInternalSkills()).toBe(true);
});
it('should return true when INSTALL_INTERNAL_SKILLS=true', () => {
process.env.INSTALL_INTERNAL_SKILLS = 'true';
expect(shouldInstallInternalSkills()).toBe(true);
});
it('should return false for other values', () => {
process.env.INSTALL_INTERNAL_SKILLS = '0';
expect(shouldInstallInternalSkills()).toBe(false);
process.env.INSTALL_INTERNAL_SKILLS = 'false';
expect(shouldInstallInternalSkills()).toBe(false);
process.env.INSTALL_INTERNAL_SKILLS = 'yes';
expect(shouldInstallInternalSkills()).toBe(false);
});
});
describe('parseAddOptions', () => {
it('should parse --all flag', () => {
const result = parseAddOptions(['source', '--all']);
expect(result.source).toEqual(['source']);
expect(result.options.all).toBe(true);
});
it('should parse --skill with wildcard', () => {
const result = parseAddOptions(['source', '--skill', '*']);
expect(result.source).toEqual(['source']);
expect(result.options.skill).toEqual(['*']);
});
it('should parse --agent with wildcard', () => {
const result = parseAddOptions(['source', '--agent', '*']);
expect(result.source).toEqual(['source']);
expect(result.options.agent).toEqual(['*']);
});
it('should parse --skill wildcard with specific agents', () => {
const result = parseAddOptions(['source', '--skill', '*', '--agent', 'claude-code']);
expect(result.source).toEqual(['source']);
expect(result.options.skill).toEqual(['*']);
expect(result.options.agent).toEqual(['claude-code']);
});
it('should parse --agent wildcard with specific skills', () => {
const result = parseAddOptions(['source', '--agent', '*', '--skill', 'my-skill']);
expect(result.source).toEqual(['source']);
expect(result.options.agent).toEqual(['*']);
expect(result.options.skill).toEqual(['my-skill']);
});
it('should parse combined flags with wildcards', () => {
const result = parseAddOptions(['source', '-g', '--skill', '*', '-y']);
expect(result.source).toEqual(['source']);
expect(result.options.global).toBe(true);
expect(result.options.skill).toEqual(['*']);
expect(result.options.yes).toBe(true);
});
it('should parse --full-depth flag', () => {
const result = parseAddOptions(['source', '--full-depth']);
expect(result.source).toEqual(['source']);
expect(result.options.fullDepth).toBe(true);
});
it('should parse --full-depth with other flags', () => {
const result = parseAddOptions(['source', '--full-depth', '--list', '-g']);
expect(result.source).toEqual(['source']);
expect(result.options.fullDepth).toBe(true);
expect(result.options.list).toBe(true);
expect(result.options.global).toBe(true);
});
});
describe('find-skills prompt with -y flag', () => {
let testDir: string;
beforeEach(() => {
testDir = join(tmpdir(), `skills-yes-flag-test-${Date.now()}`);
mkdirSync(testDir, { recursive: true });
});
afterEach(() => {
if (existsSync(testDir)) {
rmSync(testDir, { recursive: true, force: true });
}
});
it('should skip find-skills prompt when -y flag is passed', () => {
// Create a test skill
const skillDir = join(testDir, 'test-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
`---
name: yes-flag-test-skill
description: A test skill for -y flag testing
---
# Yes Flag Test Skill
This is a test skill for -y flag mode testing.
`
);
// Run with -y flag - should complete without hanging
const result = runCli(['add', testDir, '-g', '-y', '--skill', 'yes-flag-test-skill'], testDir);
// Should not contain the find-skills prompt
expect(result.stdout).not.toContain('Install the find-skills skill');
expect(result.stdout).not.toContain("One-time prompt - you won't be asked again");
// Should complete successfully
expect(result.exitCode).toBe(0);
});
});
================================================
FILE: src/add.ts
================================================
import * as p from '@clack/prompts';
import pc from 'picocolors';
import { existsSync } from 'fs';
import { homedir } from 'os';
import { sep } from 'path';
import { parseSource, getOwnerRepo, parseOwnerRepo, isRepoPrivate } from './source-parser.ts';
import { searchMultiselect } from './prompts/search-multiselect.ts';
// Helper to check if a value is a cancel symbol (works with both clack and our custom prompts)
const isCancelled = (value: unknown): value is symbol => typeof value === 'symbol';
/**
* Check if a source identifier (owner/repo format) represents a private GitHub repo.
* Returns true if private, false if public, null if unable to determine or not a GitHub repo.
*/
async function isSourcePrivate(source: string): Promise<boolean | null> {
const ownerRepo = parseOwnerRepo(source);
if (!ownerRepo) {
// Not in owner/repo format, assume not private (could be other providers)
return false;
}
return isRepoPrivate(ownerRepo.owner, ownerRepo.repo);
}
import { cloneRepo, cleanupTempDir, GitCloneError } from './git.ts';
import { discoverSkills, getSkillDisplayName, filterSkills } from './skills.ts';
import {
installSkillForAgent,
isSkillInstalled,
getCanonicalPath,
installWellKnownSkillForAgent,
type InstallMode,
} from './installer.ts';
import {
detectInstalledAgents,
agents,
getUniversalAgents,
getNonUniversalAgents,
isUniversalAgent,
} from './agents.ts';
import {
track,
setVersion,
fetchAuditData,
type AuditResponse,
type PartnerAudit,
} from './telemetry.ts';
import { wellKnownProvider, type WellKnownSkill } from './providers/index.ts';
import {
addSkillToLock,
fetchSkillFolderHash,
getGitHubToken,
isPromptDismissed,
dismissPrompt,
getLastSelectedAgents,
saveSelectedAgents,
} from './skill-lock.ts';
import { addSkillToLocalLock, computeSkillFolderHash } from './local-lock.ts';
import type { Skill, AgentType } from './types.ts';
import packageJson from '../package.json' with { type: 'json' };
export function initTelemetry(version: string): void {
setVersion(version);
}
// ─── Security Advisory ───
function riskLabel(risk: string): string {
switch (risk) {
case 'critical':
return pc.red(pc.bold('Critical Risk'));
case 'high':
return pc.red('High Risk');
case 'medium':
return pc.yellow('Med Risk');
case 'low':
return pc.green('Low Risk');
case 'safe':
return pc.green('Safe');
default:
return pc.dim('--');
}
}
function socketLabel(audit: PartnerAudit | undefined): string {
if (!audit) return pc.dim('--');
const count = audit.alerts ?? 0;
return count > 0 ? pc.red(`${count} alert${count !== 1 ? 's' : ''}`) : pc.green('0 alerts');
}
/** Pad a string to a given visible width (ignoring ANSI escape codes). */
function padEnd(str: string, width: number): string {
// Strip ANSI codes to measure visible length
const visible = str.replace(/\x1b\[[0-9;]*m/g, '');
const pad = Math.max(0, width - visible.length);
return str + ' '.repeat(pad);
}
/**
* Render a compact security table showing partner audit results.
* Returns the lines to display, or empty array if no data.
*/
function buildSecurityLines(
auditData: AuditResponse | null,
skills: Array<{ slug: string; displayName: string }>,
source: string
): string[] {
if (!auditData) return [];
// Check if we have any audit data at all
const hasAny = skills.some((s) => {
const data = auditData[s.slug];
return data && Object.keys(data).length > 0;
});
if (!hasAny) return [];
// Compute column width for skill names
const nameWidth = Math.min(Math.max(...skills.map((s) => s.displayName.length)), 36);
// Header
const lines: string[] = [];
const header =
padEnd('', nameWidth + 2) +
padEnd(pc.dim('Gen'), 18) +
padEnd(pc.dim('Socket'), 18) +
pc.dim('Snyk');
lines.push(header);
// Rows
for (const skill of skills) {
const data = auditData[skill.slug];
const name =
skill.displayName.length > nameWidth
? skill.displayName.slice(0, nameWidth - 1) + '\u2026'
: skill.displayName;
const ath = data?.ath ? riskLabel(data.ath.risk) : pc.dim('--');
const socket = data?.socket ? socketLabel(data.socket) : pc.dim('--');
const snyk = data?.snyk ? riskLabel(data.snyk.risk) : pc.dim('--');
lines.push(padEnd(pc.cyan(name), nameWidth + 2) + padEnd(ath, 18) + padEnd(socket, 18) + snyk);
}
// Footer link
lines.push('');
lines.push(`${pc.dim('Details:')} ${pc.dim(`https://skills.sh/${source}`)}`);
return lines;
}
/**
* Shortens a path for display: replaces homedir with ~ and cwd with .
* Handles both Unix and Windows path separators.
*/
function shortenPath(fullPath: string, cwd: string): string {
const home = homedir();
// Ensure we match complete path segments by checking for separator after the prefix
if (fullPath === home || fullPath.startsWith(home + sep)) {
return '~' + fullPath.slice(home.length);
}
if (fullPath === cwd || fullPath.startsWith(cwd + sep)) {
return '.' + fullPath.slice(cwd.length);
}
return fullPath;
}
/**
* Formats a list of items, truncating if too many
*/
function formatList(items: string[], maxShow: number = 5): string {
if (items.length <= maxShow) {
return items.join(', ');
}
const shown = items.slice(0, maxShow);
const remaining = items.length - maxShow;
return `${shown.join(', ')} +${remaining} more`;
}
/**
* Splits agents into universal and non-universal (symlinked) groups.
* Returns display names for each group.
*/
function splitAgentsByType(agentTypes: AgentType[]): {
universal: string[];
symlinked: string[];
} {
const universal: string[] = [];
const symlinked: string[] = [];
for (const a of agentTypes) {
if (isUniversalAgent(a)) {
universal.push(agents[a].displayName);
} else {
symlinked.push(agents[a].displayName);
}
}
return { universal, symlinked };
}
/**
* Builds summary lines showing universal vs symlinked agents
*/
function buildAgentSummaryLines(targetAgents: AgentType[], installMode: InstallMode): string[] {
const lines: string[] = [];
const { universal, symlinked } = splitAgentsByType(targetAgents);
if (installMode === 'symlink') {
if (universal.length > 0) {
lines.push(` ${pc.green('universal:')} ${formatList(universal)}`);
}
if (symlinked.length > 0) {
lines.push(` ${pc.dim('symlink →')} ${formatList(symlinked)}`);
}
} else {
// Copy mode - all agents get copies
const allNames = targetAgents.map((a) => agents[a].displayName);
lines.push(` ${pc.dim('copy →')} ${formatList(allNames)}`);
}
return lines;
}
/**
* Ensures universal agents are always included in the target agents list.
* Used when -y flag is passed or when auto-selecting agents.
*/
function ensureUniversalAgents(targetAgents: AgentType[]): AgentType[] {
const universalAgents = getUniversalAgents();
const result = [...targetAgents];
for (const ua of universalAgents) {
if (!result.includes(ua)) {
result.push(ua);
}
}
return result;
}
/**
* Builds result lines from installation results, splitting by universal vs symlinked
*/
function buildResultLines(
results: Array<{
agent: string;
symlinkFailed?: boolean;
}>,
targetAgents: AgentType[]
): string[] {
const lines: string[] = [];
// Split target agents by type
const { universal, symlinked: symlinkAgents } = splitAgentsByType(targetAgents);
// For symlink results, also track which ones actually succeeded vs failed
const successfulSymlinks = results
.filter((r) => !r.symlinkFailed && !universal.includes(r.agent))
.map((r) => r.agent);
const failedSymlinks = results.filter((r) => r.symlinkFailed).map((r) => r.agent);
if (universal.length > 0) {
lines.push(` ${pc.green('universal:')} ${formatList(universal)}`);
}
if (successfulSymlinks.length > 0) {
lines.push(` ${pc.dim('symlinked:')} ${formatList(successfulSymlinks)}`);
}
if (failedSymlinks.length > 0) {
lines.push(` ${pc.yellow('copied:')} ${formatList(failedSymlinks)}`);
}
return lines;
}
/**
* Wrapper around p.multiselect that adds a hint for keyboard usage.
* Accepts options with required labels (matching our usage pattern).
*/
function multiselect<Value>(opts: {
message: string;
options: Array<{ value: Value; label: string; hint?: string }>;
initialValues?: Value[];
required?: boolean;
}) {
return p.multiselect({
...opts,
// Cast is safe: our options always have labels, which satisfies p.Option requirements
options: opts.options as p.Option<Value>[],
message: `${opts.message} ${pc.dim('(space to toggle)')}`,
}) as Promise<Value[] | symbol>;
}
/**
* Prompts the user to select agents using interactive search.
* Pre-selects the last used agents if available.
* Saves the selection for future use.
*/
export async function promptForAgents(
message: string,
choices: Array<{ value: AgentType; label: string; hint?: string }>
): Promise<AgentType[] | symbol> {
// Get last selected agents to pre-select
let lastSelected: string[] | undefined;
try {
lastSelected = await getLastSelectedAgents();
} catch {
// Silently ignore errors reading lock file
}
const validAgents = choices.map((c) => c.value);
// Default agents to pre-select when no valid history exists
const defaultAgents: AgentType[] = ['claude-code', 'opencode', 'codex'];
const defaultValues = defaultAgents.filter((a) => validAgents.includes(a));
let initialValues: AgentType[] = [];
if (lastSelected && lastSelected.length > 0) {
// Filter stored agents against currently valid agents
initialValues = lastSelected.filter((a) => validAgents.includes(a as AgentType)) as AgentType[];
}
// If no valid selection from history, use defaults
if (initialValues.length === 0) {
initialValues = defaultValues;
}
const selected = await searchMultiselect({
message,
items: choices,
initialSelected: initialValues,
required: true,
});
if (!isCancelled(selected)) {
// Save selection for next time
try {
await saveSelectedAgents(selected as string[]);
} catch {
// Silently ignore errors writing lock file
}
}
return selected as AgentType[] | symbol;
}
/**
* Interactive agent selection using fuzzy search.
* Shows universal agents as locked (always selected), and other agents as selectable.
*/
async function selectAgentsInteractive(options: {
global?: boolean;
}): Promise<AgentType[] | symbol> {
// Filter out agents that don't support global installation when --global is used
const supportsGlobalFilter = (a: AgentType) => !options.global || agents[a].globalSkillsDir;
const universalAgents = getUniversalAgents().filter(supportsGlobalFilter);
const otherAgents = getNonUniversalAgents().filter(supportsGlobalFilter);
// Universal agents shown as locked section
const universalSection = {
title: 'Universal (.agents/skills)',
items: universalAgents.map((a) => ({
value: a,
label: agents[a].displayName,
})),
};
// Other agents are selectable with their skillsDir as hint
const otherChoices = otherAgents.map((a) => ({
value: a,
label: agents[a].displayName,
hint: options.global ? agents[a].globalSkillsDir! : agents[a].skillsDir,
}));
// Get last selected agents (filter to only non-universal ones for initial selection)
let lastSelected: string[] | undefined;
try {
lastSelected = await getLastSelectedAgents();
} catch {
// Silently ignore errors
}
const initialSelected = lastSelected
? (lastSelected.filter(
(a) => otherAgents.includes(a as AgentType) && !universalAgents.includes(a as AgentType)
) as AgentType[])
: [];
const selected = await searchMultiselect({
message: 'Which agents do you want to install to?',
items: otherChoices,
initialSelected,
lockedSection: universalSection,
});
if (!isCancelled(selected)) {
// Save selection (all agents including universal)
try {
await saveSelectedAgents(selected as string[]);
} catch {
// Silently ignore errors
}
}
return selected as AgentType[] | symbol;
}
const version = packageJson.version;
setVersion(version);
export interface AddOptions {
global?: boolean;
agent?: string[];
yes?: boolean;
skill?: string[];
list?: boolean;
all?: boolean;
fullDepth?: boolean;
copy?: boolean;
}
/**
* Handle skills from a well-known endpoint (RFC 8615).
* Discovers skills from /.well-known/skills/index.json
*/
async function handleWellKnownSkills(
source: string,
url: string,
options: AddOptions,
spinner: ReturnType<typeof p.spinner>
): Promise<void> {
spinner.start('Discovering skills from well-known endpoint...');
// Fetch all skills from the well-known endpoint
const skills = await wellKnownProvider.fetchAllSkills(url);
if (skills.length === 0) {
spinner.stop(pc.red('No skills found'));
p.outro(
pc.red(
'No skills found at this URL. Make sure the server has a /.well-known/skills/index.json file.'
)
);
process.exit(1);
}
spinner.stop(`Found ${pc.green(skills.length)} skill${skills.length > 1 ? 's' : ''}`);
// Log discovered skills
for (const skill of skills) {
p.log.info(`Skill: ${pc.cyan(skill.installName)}`);
p.log.message(pc.dim(skill.description));
if (skill.files.size > 1) {
p.log.message(pc.dim(` Files: ${Array.from(skill.files.keys()).join(', ')}`));
}
}
if (options.list) {
console.log();
p.log.step(pc.bold('Available Skills'));
for (const skill of skills) {
p.log.message(` ${pc.cyan(skill.installName)}`);
p.log.message(` ${pc.dim(skill.description)}`);
if (skill.files.size > 1) {
p.log.message(` ${pc.dim(`Files: ${skill.files.size}`)}`);
}
}
console.log();
p.outro('Run without --list to install');
process.exit(0);
}
// Filter skills if --skill option is provided
let selectedSkills: WellKnownSkill[];
if (options.skill?.includes('*')) {
// --skill '*' selects all skills
selectedSkills = skills;
p.log.info(`Installing all ${skills.length} skills`);
} else if (options.skill && options.skill.length > 0) {
selectedSkills = skills.filter((s) =>
options.skill!.some(
(name) =>
s.installName.toLowerCase() === name.toLowerCase() ||
s.name.toLowerCase() === name.toLowerCase()
)
);
if (selectedSkills.length === 0) {
p.log.error(`No matching skills found for: ${options.skill.join(', ')}`);
p.log.info('Available skills:');
for (const s of skills) {
p.log.message(` - ${s.installName}`);
}
process.exit(1);
}
} else if (skills.length === 1) {
selectedSkills = skills;
const firstSkill = skills[0]!;
p.log.info(`Skill: ${pc.cyan(firstSkill.installName)}`);
} else if (options.yes) {
selectedSkills = skills;
p.log.info(`Installing all ${skills.length} skills`);
} else {
// Prompt user to select skills
const skillChoices = skills.map((s) => ({
value: s,
label: s.installName,
hint: s.description.length > 60 ? s.description.slice(0, 57) + '...' : s.description,
}));
const selected = await multiselect({
message: 'Select skills to install',
options: skillChoices,
required: true,
});
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
process.exit(0);
}
selectedSkills = selected as WellKnownSkill[];
}
// Detect agents
let targetAgents: AgentType[];
const validAgents = Object.keys(agents);
if (options.agent?.includes('*')) {
// --agent '*' selects all agents
targetAgents = validAgents as AgentType[];
p.log.info(`Installing to all ${targetAgents.length} agents`);
} else if (options.agent && options.agent.length > 0) {
const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
if (invalidAgents.length > 0) {
p.log.error(`Invalid agents: ${invalidAgents.join(', ')}`);
p.log.info(`Valid agents: ${validAgents.join(', ')}`);
process.exit(1);
}
targetAgents = options.agent as AgentType[];
} else {
spinner.start('Loading agents...');
const installedAgents = await detectInstalledAgents();
const totalAgents = Object.keys(agents).length;
spinner.stop(`${totalAgents} agents`);
if (installedAgents.length === 0) {
if (options.yes) {
targetAgents = validAgents as AgentType[];
p.log.info('Installing to all agents');
} else {
p.log.info('Select agents to install skills to');
const allAgentChoices = Object.entries(agents).map(([key, config]) => ({
value: key as AgentType,
label: config.displayName,
}));
// Use helper to prompt with search
const selected = await promptForAgents(
'Which agents do you want to install to?',
allAgentChoices
);
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
process.exit(0);
}
targetAgents = selected as AgentType[];
}
} else if (installedAgents.length === 1 || options.yes) {
// Auto-select detected agents + ensure universal agents are included
targetAgents = ensureUniversalAgents(installedAgents);
if (installedAgents.length === 1) {
const firstAgent = installedAgents[0]!;
p.log.info(`Installing to: ${pc.cyan(agents[firstAgent].displayName)}`);
} else {
p.log.info(
`Installing to: ${installedAgents.map((a) => pc.cyan(agents[a].displayName)).join(', ')}`
);
}
} else {
const selected = await selectAgentsInteractive({ global: options.global });
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
process.exit(0);
}
targetAgents = selected as AgentType[];
}
}
let installGlobally = options.global ?? false;
// Check if any selected agents support global installation
const supportsGlobal = targetAgents.some((a) => agents[a].globalSkillsDir !== undefined);
if (options.global === undefined && !options.yes && supportsGlobal) {
const scope = await p.select({
message: 'Installation scope',
options: [
{
value: false,
label: 'Project',
hint: 'Install in current directory (committed with your project)',
},
{
value: true,
label: 'Global',
hint: 'Install in home directory (available across all projects)',
},
],
});
if (p.isCancel(scope)) {
p.cancel('Installation cancelled');
process.exit(0);
}
installGlobally = scope as boolean;
}
// Determine install mode (symlink vs copy)
let installMode: InstallMode = options.copy ? 'copy' : 'symlink';
// Only prompt for install mode when there are multiple unique target directories.
// When all selected agents share the same skillsDir, symlink vs copy is meaningless.
const uniqueDirs = new Set(targetAgents.map((a) => agents[a].skillsDir));
if (!options.copy && !options.yes && uniqueDirs.size > 1) {
const modeChoice = await p.select({
message: 'Installation method',
options: [
{
value: 'symlink',
label: 'Symlink (Recommended)',
hint: 'Single source of truth, easy updates',
},
{ value: 'copy', label: 'Copy to all agents', hint: 'Independent copies for each agent' },
],
});
if (p.isCancel(modeChoice)) {
p.cancel('Installation cancelled');
process.exit(0);
}
installMode = modeChoice as InstallMode;
} else if (uniqueDirs.size <= 1) {
// Single target directory — default to copy (no symlink needed)
installMode = 'copy';
}
const cwd = process.cwd();
// Build installation summary
const summaryLines: string[] = [];
const agentNames = targetAgents.map((a) => agents[a].displayName);
// Check if any skill will be overwritten (parallel)
const overwriteChecks = await Promise.all(
selectedSkills.flatMap((skill) =>
targetAgents.map(async (agent) => ({
skillName: skill.installName,
agent,
installed: await isSkillInstalled(skill.installName, agent, { global: installGlobally }),
}))
)
);
const overwriteStatus = new Map<string, Map<string, boolean>>();
for (const { skillName, agent, installed } of overwriteChecks) {
if (!overwriteStatus.has(skillName)) {
overwriteStatus.set(skillName, new Map());
}
overwriteStatus.get(skillName)!.set(agent, installed);
}
for (const skill of selectedSkills) {
if (summaryLines.length > 0) summaryLines.push('');
const canonicalPath = getCanonicalPath(skill.installName, { global: installGlobally });
const shortCanonical = shortenPath(canonicalPath, cwd);
summaryLines.push(`${pc.cyan(shortCanonical)}`);
summaryLines.push(...buildAgentSummaryLines(targetAgents, installMode));
if (skill.files.size > 1) {
summaryLines.push(` ${pc.dim('files:')} ${skill.files.size}`);
}
const skillOverwrites = overwriteStatus.get(skill.installName);
const overwriteAgents = targetAgents
.filter((a) => skillOverwrites?.get(a))
.map((a) => agents[a].displayName);
if (overwriteAgents.length > 0) {
summaryLines.push(` ${pc.yellow('overwrites:')} ${formatList(overwriteAgents)}`);
}
}
console.log();
p.note(summaryLines.join('\n'), 'Installation Summary');
if (!options.yes) {
const confirmed = await p.confirm({ message: 'Proceed with installation?' });
if (p.isCancel(confirmed) || !confirmed) {
p.cancel('Installation cancelled');
process.exit(0);
}
}
spinner.start('Installing skills...');
const results: {
skill: string;
agent: string;
success: boolean;
path: string;
canonicalPath?: string;
mode: InstallMode;
symlinkFailed?: boolean;
error?: string;
}[] = [];
for (const skill of selectedSkills) {
for (const agent of targetAgents) {
const result = await installWellKnownSkillForAgent(skill, agent, {
global: installGlobally,
mode: installMode,
});
results.push({
skill: skill.installName,
agent: agents[agent].displayName,
...result,
});
}
}
spinner.stop('Installation complete');
console.log();
const successful = results.filter((r) => r.success);
const failed = results.filter((r) => !r.success);
// Track installation
const sourceIdentifier = wellKnownProvider.getSourceIdentifier(url);
// Build skillFiles map: { skillName: sourceUrl }
const skillFiles: Record<string, string> = {};
for (const skill of selectedSkills) {
skillFiles[skill.installName] = skill.sourceUrl;
}
// Skip telemetry for private GitHub repos
const isPrivate = await isSourcePrivate(sourceIdentifier);
if (isPrivate !== true) {
// Only send telemetry if repo is public (isPrivate === false) or we can't determine (null for non-GitHub sources)
track({
event: 'install',
source: sourceIdentifier,
skills: selectedSkills.map((s) => s.installName).join(','),
agents: targetAgents.join(','),
...(installGlobally && { global: '1' }),
skillFiles: JSON.stringify(skillFiles),
sourceType: 'well-known',
});
}
// Add to skill lock file for update tracking (only for global installs)
if (successful.length > 0 && installGlobally) {
const successfulSkillNames = new Set(successful.map((r) => r.skill));
for (const skill of selectedSkills) {
if (successfulSkillNames.has(skill.installName)) {
try {
await addSkillToLock(skill.installName, {
source: sourceIdentifier,
sourceType: 'well-known',
sourceUrl: skill.sourceUrl,
skillFolderHash: '', // Well-known skills don't have a folder hash
});
} catch {
// Don't fail installation if lock file update fails
}
}
}
}
// Add to local lock file for project-scoped installs
if (successful.length > 0 && !installGlobally) {
const successfulSkillNames = new Set(successful.map((r) => r.skill));
for (const skill of selectedSkills) {
if (successfulSkillNames.has(skill.installName)) {
try {
const matchingResult = successful.find((r) => r.skill === skill.installName);
const installDir = matchingResult?.canonicalPath || matchingResult?.path;
if (installDir) {
const computedHash = await computeSkillFolderHash(installDir);
await addSkillToLocalLock(
skill.installName,
{
source: sourceIdentifier,
sourceType: 'well-known',
computedHash,
},
cwd
);
}
} catch {
// Don't fail installation if lock file update fails
}
}
}
}
if (successful.length > 0) {
const bySkill = new Map<string, typeof results>();
for (const r of successful) {
const skillResults = bySkill.get(r.skill) || [];
skillResults.push(r);
bySkill.set(r.skill, skillResults);
}
const skillCount = bySkill.size;
const symlinkFailures = successful.filter((r) => r.mode === 'symlink' && r.symlinkFailed);
const copiedAgents = symlinkFailures.map((r) => r.agent);
const resultLines: string[] = [];
for (const [skillName, skillResults] of bySkill) {
const firstResult = skillResults[0]!;
if (firstResult.mode === 'copy') {
// Copy mode: show skill name and list all agent paths
resultLines.push(`${pc.green('✓')} ${skillName} ${pc.dim('(copied)')}`);
for (const r of skillResults) {
const shortPath = shortenPath(r.path, cwd);
resultLines.push(` ${pc.dim('→')} ${shortPath}`);
}
} else {
// Symlink mode: show canonical path and universal/symlinked agents
if (firstResult.canonicalPath) {
const shortPath = shortenPath(firstResult.canonicalPath, cwd);
resultLines.push(`${pc.green('✓')} ${shortPath}`);
} else {
resultLines.push(`${pc.green('✓')} ${skillName}`);
}
resultLines.push(...buildResultLines(skillResults, targetAgents));
}
}
const title = pc.green(`Installed ${skillCount} skill${skillCount !== 1 ? 's' : ''}`);
p.note(resultLines.join('\n'), title);
// Show symlink failure warning (only for symlink mode)
if (symlinkFailures.length > 0) {
p.log.warn(pc.yellow(`Symlinks failed for: ${formatList(copiedAgents)}`));
p.log.message(
pc.dim(
' Files were copied instead. On Windows, enable Developer Mode for symlink support.'
)
);
}
}
if (failed.length > 0) {
console.log();
p.log.error(pc.red(`Failed to install ${failed.length}`));
for (const r of failed) {
p.log.message(` ${pc.red('✗')} ${r.skill} → ${r.agent}: ${pc.dim(r.error)}`);
}
}
console.log();
p.outro(
pc.green('Done!') + pc.dim(' Review skills before use; they run with full agent permissions.')
);
// Prompt for find-skills after successful install
await promptForFindSkills(options, targetAgents);
}
export async function runAdd(args: string[], options: AddOptions = {}): Promise<void> {
const source = args[0];
let installTipShown = false;
const showInstallTip = (): void => {
if (installTipShown) return;
p.log.message(
pc.dim('Tip: use the --yes (-y) and --global (-g) flags to install without prompts.')
);
installTipShown = true;
};
if (!source) {
console.log();
console.log(
pc.bgRed(pc.white(pc.bold(' ERROR '))) + ' ' + pc.red('Missing required argument: source')
);
console.log();
console.log(pc.dim(' Usage:'));
console.log(` ${pc.cyan('npx skills add')} ${pc.yellow('<source>')} ${pc.dim('[options]')}`);
console.log();
console.log(pc.dim(' Example:'));
console.log(` ${pc.cyan('npx skills add')} ${pc.yellow('vercel-labs/agent-skills')}`);
console.log();
process.exit(1);
}
// --all implies --skill '*' and --agent '*' and -y
if (options.all) {
options.skill = ['*'];
options.agent = ['*'];
options.yes = true;
}
console.log();
p.intro(pc.bgCyan(pc.black(' skills ')));
if (!process.stdin.isTTY) {
showInstallTip();
}
let tempDir: string | null = null;
try {
const spinner = p.spinner();
spinner.start('Parsing source...');
const parsed = parseSource(source);
spinner.stop(
`Source: ${parsed.type === 'local' ? parsed.localPath! : parsed.url}${parsed.ref ? ` @ ${pc.yellow(parsed.ref)}` : ''}${parsed.subpath ? ` (${parsed.subpath})` : ''}${parsed.skillFilter ? ` ${pc.dim('@')}${pc.cyan(parsed.skillFilter)}` : ''}`
);
// Handle well-known skills from arbitrary URLs
if (parsed.type === 'well-known') {
await handleWellKnownSkills(source, parsed.url, options, spinner);
return;
}
let skillsDir: string;
if (parsed.type === 'local') {
// Use local path directly, no cloning needed
spinner.start('Validating local path...');
if (!existsSync(parsed.localPath!)) {
spinner.stop(pc.red('Path not found'));
p.outro(pc.red(`Local path does not exist: ${parsed.localPath}`));
process.exit(1);
}
skillsDir = parsed.localPath!;
spinner.stop('Local path validated');
} else {
// Clone repository for remote sources
spinner.start('Cloning repository...');
tempDir = await cloneRepo(parsed.url, parsed.ref);
skillsDir = tempDir;
spinner.stop('Repository cloned');
}
// If skillFilter is present from @skill syntax (e.g., owner/repo@skill-name),
// merge it into options.skill
if (parsed.skillFilter) {
options.skill = options.skill || [];
if (!options.skill.includes(parsed.skillFilter)) {
options.skill.push(parsed.skillFilter);
}
}
// Include internal skills when a specific skill is explicitly requested
// (via --skill or @skill syntax)
const includeInternal = !!(options.skill && options.skill.length > 0);
spinner.start('Discovering skills...');
const skills = await discoverSkills(skillsDir, parsed.subpath, {
includeInternal,
fullDepth: options.fullDepth,
});
if (skills.length === 0) {
spinner.stop(pc.red('No skills found'));
p.outro(
pc.red('No valid skills found. Skills require a SKILL.md with name and description.')
);
await cleanup(tempDir);
process.exit(1);
}
spinner.stop(`Found ${pc.green(skills.length)} skill${skills.length > 1 ? 's' : ''}`);
if (options.list) {
console.log();
p.log.step(pc.bold('Available Skills'));
// Group available skills by plugin for list output
const groupedSkills: Record<string, Skill[]> = {};
const ungroupedSkills: Skill[] = [];
for (const skill of skills) {
if (skill.pluginName) {
const group = skill.pluginName;
if (!groupedSkills[group]) groupedSkills[group] = [];
groupedSkills[group].push(skill);
} else {
ungroupedSkills.push(skill);
}
}
// Print groups
const sortedGroups = Object.keys(groupedSkills).sort();
for (const group of sortedGroups) {
// Convert kebab-case to Title Case for display header
const title = group
.split('-')
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
console.log(pc.bold(title));
for (const skill of groupedSkills[group]!) {
p.log.message(` ${pc.cyan(getSkillDisplayName(skill))}`);
p.log.message(` ${pc.dim(skill.description)}`);
}
console.log();
}
// Print ungrouped
if (ungroupedSkills.length > 0) {
if (sortedGroups.length > 0) console.log(pc.bold('General'));
for (const skill of ungroupedSkills) {
p.log.message(` ${pc.cyan(getSkillDisplayName(skill))}`);
p.log.message(` ${pc.dim(skill.description)}`);
}
}
console.log();
p.outro('Use --skill <name> to install specific skills');
await cleanup(tempDir);
process.exit(0);
}
let selectedSkills: Skill[];
if (options.skill?.includes('*')) {
// --skill '*' selects all skills
selectedSkills = skills;
p.log.info(`Installing all ${skills.length} skills`);
} else if (options.skill && options.skill.length > 0) {
selectedSkills = filterSkills(skills, options.skill);
if (selectedSkills.length === 0) {
p.log.error(`No matching skills found for: ${options.skill.join(', ')}`);
p.log.info('Available skills:');
for (const s of skills) {
p.log.message(` - ${getSkillDisplayName(s)}`);
}
await cleanup(tempDir);
process.exit(1);
}
p.log.info(
`Selected ${selectedSkills.length} skill${selectedSkills.length !== 1 ? 's' : ''}: ${selectedSkills.map((s) => pc.cyan(getSkillDisplayName(s))).join(', ')}`
);
} else if (skills.length === 1) {
selectedSkills = skills;
const firstSkill = skills[0]!;
p.log.info(`Skill: ${pc.cyan(getSkillDisplayName(firstSkill))}`);
p.log.message(pc.dim(firstSkill.description));
} else if (options.yes) {
selectedSkills = skills;
p.log.info(`Installing all ${skills.length} skills`);
} else {
// Sort skills by plugin name first, then by skill name
const sortedSkills = [...skills].sort((a, b) => {
if (a.pluginName && !b.pluginName) return -1;
if (!a.pluginName && b.pluginName) return 1;
if (a.pluginName && b.pluginName && a.pluginName !== b.pluginName) {
return a.pluginName.localeCompare(b.pluginName);
}
return getSkillDisplayName(a).localeCompare(getSkillDisplayName(b));
});
// Check if any skills have plugin grouping
const hasGroups = sortedSkills.some((s) => s.pluginName);
let selected: Skill[] | symbol;
if (hasGroups) {
// Build grouped options for groupMultiselect
const kebabToTitle = (s: string) =>
s
.split('-')
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
const grouped: Record<string, p.Option<Skill>[]> = {};
for (const s of sortedSkills) {
const groupName = s.pluginName ? kebabToTitle(s.pluginName) : 'Other';
if (!grouped[groupName]) grouped[groupName] = [];
grouped[groupName]!.push({
value: s,
label: getSkillDisplayName(s),
hint: s.description.length > 60 ? s.description.slice(0, 57) + '...' : s.description,
});
}
selected = await p.groupMultiselect({
message: `Select skills to install ${pc.dim('(space to toggle)')}`,
options: grouped,
required: true,
});
} else {
const skillChoices = sortedSkills.map((s) => ({
value: s,
label: getSkillDisplayName(s),
hint: s.description.length > 60 ? s.description.slice(0, 57) + '...' : s.description,
}));
selected = await multiselect({
message: 'Select skills to install',
options: skillChoices,
required: true,
});
}
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
selectedSkills = selected as Skill[];
}
// Kick off security audit fetch early (non-blocking) so it runs
// in parallel with agent selection, scope, and mode prompts.
const ownerRepoForAudit = getOwnerRepo(parsed);
const auditPromise = ownerRepoForAudit
? fetchAuditData(
ownerRepoForAudit,
selectedSkills.map((s) => getSkillDisplayName(s))
)
: Promise.resolve(null);
let targetAgents: AgentType[];
const validAgents = Object.keys(agents);
if (options.agent?.includes('*')) {
// --agent '*' selects all agents
targetAgents = validAgents as AgentType[];
p.log.info(`Installing to all ${targetAgents.length} agents`);
} else if (options.agent && options.agent.length > 0) {
const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
if (invalidAgents.length > 0) {
p.log.error(`Invalid agents: ${invalidAgents.join(', ')}`);
p.log.info(`Valid agents: ${validAgents.join(', ')}`);
await cleanup(tempDir);
process.exit(1);
}
targetAgents = options.agent as AgentType[];
} else {
spinner.start('Loading agents...');
const installedAgents = await detectInstalledAgents();
const totalAgents = Object.keys(agents).length;
spinner.stop(`${totalAgents} agents`);
if (installedAgents.length === 0) {
if (options.yes) {
targetAgents = validAgents as AgentType[];
p.log.info('Installing to all agents');
} else {
p.log.info('Select agents to install skills to');
const allAgentChoices = Object.entries(agents).map(([key, config]) => ({
value: key as AgentType,
label: config.displayName,
}));
// Use helper to prompt with search
const selected = await promptForAgents(
'Which agents do you want to install to?',
allAgentChoices
);
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
targetAgents = selected as AgentType[];
}
} else if (installedAgents.length === 1 || options.yes) {
// Auto-select detected agents + ensure universal agents are included
targetAgents = ensureUniversalAgents(installedAgents);
if (installedAgents.length === 1) {
const firstAgent = installedAgents[0]!;
p.log.info(`Installing to: ${pc.cyan(agents[firstAgent].displayName)}`);
} else {
p.log.info(
`Installing to: ${installedAgents.map((a) => pc.cyan(agents[a].displayName)).join(', ')}`
);
}
} else {
const selected = await selectAgentsInteractive({ global: options.global });
if (p.isCancel(selected)) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
targetAgents = selected as AgentType[];
}
}
let installGlobally = options.global ?? false;
// Check if any selected agents support global installation
const supportsGlobal = targetAgents.some((a) => agents[a].globalSkillsDir !== undefined);
if (options.global === undefined && !options.yes && supportsGlobal) {
const scope = await p.select({
message: 'Installation scope',
options: [
{
value: false,
label: 'Project',
hint: 'Install in current directory (committed with your project)',
},
{
value: true,
label: 'Global',
hint: 'Install in home directory (available across all projects)',
},
],
});
if (p.isCancel(scope)) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
installGlobally = scope as boolean;
}
// Determine install mode (symlink vs copy)
let installMode: InstallMode = options.copy ? 'copy' : 'symlink';
// Only prompt for install mode when there are multiple unique target directories.
// When all selected agents share the same skillsDir, symlink vs copy is meaningless.
const uniqueDirs = new Set(targetAgents.map((a) => agents[a].skillsDir));
if (!options.copy && !options.yes && uniqueDirs.size > 1) {
const modeChoice = await p.select({
message: 'Installation method',
options: [
{
value: 'symlink',
label: 'Symlink (Recommended)',
hint: 'Single source of truth, easy updates',
},
{ value: 'copy', label: 'Copy to all agents', hint: 'Independent copies for each agent' },
],
});
if (p.isCancel(modeChoice)) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
installMode = modeChoice as InstallMode;
} else if (uniqueDirs.size <= 1) {
// Single target directory — default to copy (no symlink needed)
installMode = 'copy';
}
const cwd = process.cwd();
// Build installation summary
const summaryLines: string[] = [];
const agentNames = targetAgents.map((a) => agents[a].displayName);
// Check if any skill will be overwritten (parallel)
const overwriteChecks = await Promise.all(
selectedSkills.flatMap((skill) =>
targetAgents.map(async (agent) => ({
skillName: skill.name,
agent,
installed: await isSkillInstalled(skill.name, agent, { global: installGlobally }),
}))
)
);
const overwriteStatus = new Map<string, Map<string, boolean>>();
for (const { skillName, agent, installed } of overwriteChecks) {
if (!overwriteStatus.has(skillName)) {
overwriteStatus.set(skillName, new Map());
}
overwriteStatus.get(skillName)!.set(agent, installed);
}
// Group selected skills for summary
const groupedSummary: Record<string, Skill[]> = {};
const ungroupedSummary: Skill[] = [];
for (const skill of selectedSkills) {
if (skill.pluginName) {
const group = skill.pluginName;
if (!groupedSummary[group]) groupedSummary[group] = [];
groupedSummary[group].push(skill);
} else {
ungroupedSummary.push(skill);
}
}
// Helper to print summary lines for a list of skills
const printSkillSummary = (skills: Skill[]) => {
for (const skill of skills) {
if (summaryLines.length > 0) summaryLines.push('');
const canonicalPath = getCanonicalPath(skill.name, { global: installGlobally });
const shortCanonical = shortenPath(canonicalPath, cwd);
summaryLines.push(`${pc.cyan(shortCanonical)}`);
summaryLines.push(...buildAgentSummaryLines(targetAgents, installMode));
const skillOverwrites = overwriteStatus.get(skill.name);
const overwriteAgents = targetAgents
.filter((a) => skillOverwrites?.get(a))
.map((a) => agents[a].displayName);
if (overwriteAgents.length > 0) {
summaryLines.push(` ${pc.yellow('overwrites:')} ${formatList(overwriteAgents)}`);
}
}
};
// Build grouped summary
const sortedGroups = Object.keys(groupedSummary).sort();
for (const group of sortedGroups) {
const title = group
.split('-')
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
summaryLines.push('');
summaryLines.push(pc.bold(title));
printSkillSummary(groupedSummary[group]!);
}
if (ungroupedSummary.length > 0) {
if (sortedGroups.length > 0) {
summaryLines.push('');
summaryLines.push(pc.bold('General'));
}
printSkillSummary(ungroupedSummary);
}
console.log();
p.note(summaryLines.join('\n'), 'Installation Summary');
// Await and display security audit results (started earlier in parallel)
// Wrapped in try/catch so a failed audit fetch never blocks installation.
try {
const auditData = await auditPromise;
if (auditData && ownerRepoForAudit) {
const securityLines = buildSecurityLines(
auditData,
selectedSkills.map((s) => ({
slug: getSkillDisplayName(s),
displayName: getSkillDisplayName(s),
})),
ownerRepoForAudit
);
if (securityLines.length > 0) {
p.note(securityLines.join('\n'), 'Security Risk Assessments');
}
}
} catch {
// Silently skip — security info is advisory only
}
if (!options.yes) {
const confirmed = await p.confirm({ message: 'Proceed with installation?' });
if (p.isCancel(confirmed) || !confirmed) {
p.cancel('Installation cancelled');
await cleanup(tempDir);
process.exit(0);
}
}
spinner.start('Installing skills...');
const results: {
skill: string;
agent: string;
success: boolean;
path: string;
canonicalPath?: string;
mode: InstallMode;
symlinkFailed?: boolean;
error?: string;
pluginName?: string;
}[] = [];
for (const skill of selectedSkills) {
for (const agent of targetAgents) {
const result = await installSkillForAgent(skill, agent, {
global: installGlobally,
mode: installMode,
});
results.push({
skill: getSkillDisplayName(skill),
agent: agents[agent].displayName,
pluginName: skill.pluginName,
...result,
});
}
}
spinner.stop('Installation complete');
console.log();
const successful = results.filter((r) => r.success);
const failed = results.filter((r) => !r.success);
// Track installation result
// Build skillFiles map: { skillName: relative path to SKILL.md from repo root }
const skillFiles: Record<string, string> = {};
for (const skill of selectedSkills) {
// skill.path is absolute, compute relative from tempDir (repo root)
let relativePath: string;
if (tempDir && skill.path === tempDir) {
// Skill is at root level of repo
relativePath = 'SKILL.md';
} else if (tempDir && skill.path.startsWith(tempDir + sep)) {
// Compute path relative to repo root (tempDir), not search path
// Use forward slashes for telemetry (URL-style paths)
relativePath =
skill.path
.slice(tempDir.length + 1)
.split(sep)
.join('/') + '/SKILL.md';
} else {
// Local path - skip telemetry for local installs
continue;
}
skillFiles[skill.name] = relativePath;
}
// Normalize source to owner/repo format for telemetry
const normalizedSource = getOwnerRepo(parsed);
// Preserve SSH URLs in lock files instead of normalizing to owner/repo shorthand.
// When normalizedSource is used, parseSource() later resolves it to HTTPS,
// breaking restore for private repos that require SSH authentication.
const isSSH = parsed.url.startsWith('git@');
const lockSource = isSSH ? parsed.url : normalizedSource;
// Only track if we have a valid remote source and it's not a private repo
if (normalizedSource) {
const ownerRepo = parseOwnerRepo(normalizedSource);
if (ownerRepo) {
// Check if repo is private - skip telemetry for private repos
const isPrivate = await isRepoPrivate(ownerRepo.owner, ownerRepo.repo);
// Only send telemetry if repo is public (isPrivate === false)
// If we can't determine (null), err on the side of caution and skip telemetry
if (isPrivate === false) {
track({
event: 'install',
source: normalizedSource,
skills: selectedSkills.map((s) => s.name).join(','),
agents: targetAgents.join(','),
...(installGlobally && { global: '1' }),
skillFiles: JSON.stringify(skillFiles),
});
}
} else {
// If we can't parse owner/repo, still send telemetry (for non-GitHub sources)
track({
event: 'install',
source: normalizedSource,
skills: selectedSkills.map((s) => s.name).join(','),
agents: targetAgents.join(','),
...(installGlobally && { global: '1' }),
skillFiles: JSON.stringify(skillFiles),
});
}
}
// Add to skill lock file for update tracking (only for global installs)
if (successful.length > 0 && installGlobally && normalizedSource) {
const successfulSkillNames = new Set(successful.map((r) => r.skill));
for (const skill of selectedSkills) {
const skillDisplayName = getSkillDisplayName(skill);
if (successfulSkillNames.has(skillDisplayName)) {
try {
// Fetch the folder hash from GitHub Trees API
let skillFolderHash = '';
const skillPathValue = skillFiles[skill.name];
if (parsed.type === 'github' && skillPathValue) {
const token = getGitHubToken();
const hash = await fetchSkillFolderHash(normalizedSource, skillPathValue, token);
if (hash) skillFolderHash = hash;
}
await addSkillToLock(skill.name, {
source: lockSource || normalizedSource,
sourceType: parsed.type,
sourceUrl: parsed.url,
skillPath: skillPathValue,
skillFolderHash,
pluginName: skill.pluginName,
});
} catch {
// Don't fail installation if lock file update fails
}
}
}
}
// Add to local lock file for project-scoped installs
if (successful.length > 0 && !installGlobally) {
const successfulSkillNames = new Set(successful.map((r) => r.skill));
for (const skill of selectedSkills) {
const skillDisplayName = getSkillDisplayName(skill);
if (successfulSkillNames.has(skillDisplayName)) {
try {
const computedHash = await computeSkillFolderHash(skill.path);
await addSkillToLocalLock(
skill.name,
{
source: lockSource || parsed.url,
sourceType: parsed.type,
computedHash,
},
cwd
);
} catch {
// Don't fail installation if lock file update fails
}
}
}
}
if (successful.length > 0) {
const bySkill = new Map<string, typeof results>();
// Group results by plugin name
const groupedResults: Record<string, typeof results> = {};
const ungroupedResults: typeof results = [];
for (const r of successful) {
const skillResults = bySkill.get(r.skill) || [];
skillResults.push(r);
bySkill.set(r.skill, skillResults);
// We only need to group once per skill (take the first result for that skill)
if (skillResults.length === 1) {
if (r.pluginName) {
const group = r.pluginName;
if (!groupedResults[group]) groupedResults[group] = [];
// We'll store just one entry per skill here to drive the loop
groupedResults[group].push(r);
} else {
ungroupedResults.push(r);
}
}
}
const skillCount = bySkill.size;
const symlinkFailures = successful.filter((r) => r.mode === 'symlink' && r.symlinkFailed);
const copiedAgents = symlinkFailures.map((r) => r.agent);
const resultLines: string[] = [];
const printSkillResults = (entries: typeof results) => {
for (const entry of entries) {
const skillResults = bySkill.get(entry.skill) || [];
const firstResult = skillResults[0]!;
if (firstResult.mode === 'copy') {
// Copy mode: show skill name and list all agent paths
resultLines.push(`${pc.green('✓')} ${entry.skill} ${pc.dim('(copied)')}`);
for (const r of skillResults) {
const shortPath = shortenPath(r.path, cwd);
resultLines.push(` ${pc.dim('→')} ${shortPath}`);
}
} else {
// Symlink mode: show canonical path and universal/symlinked agents
if (firstResult.canonicalPath) {
const shortPath = shortenPath(firstResult.canonicalPath, cwd);
resultLines.push(`${pc.green('✓')} ${shortPath}`);
} else {
resultLines.push(`${pc.green('✓')} ${entry.skill}`);
}
resultLines.push(...buildResultLines(skillResults, targetAgents));
}
}
};
// Print grouped results
const sortedResultGroups = Object.keys(groupedResults).sort();
for (const group of sortedResultGroups) {
const title = group
.split('-')
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
resultLines.push('');
resultLines.push(pc.bold(title));
printSkillResults(groupedResults[group]!);
}
if (ungroupedResults.length > 0) {
if (sortedResultGroups.length > 0) {
resultLines.push('');
resultLines.push(pc.bold('General'));
}
printSkillResults(ungroupedResults);
}
const title = pc.green(`Installed ${skillCount} skill${skillCount !== 1 ? 's' : ''}`);
p.note(resultLines.join('\n'), title);
// Show symlink failure warning (only for symlink mode)
if (symlinkFailures.length > 0) {
p.log.warn(pc.yellow(`Symlinks failed for: ${formatList(copiedAgents)}`));
p.log.message(
pc.dim(
' Files were copied instead. On Windows, enable Developer Mode for symlink support.'
)
);
}
}
if (failed.length > 0) {
console.log();
p.log.error(pc.red(`Failed to install ${failed.length}`));
for (const r of failed) {
p.log.message(` ${pc.red('✗')} ${r.skill} → ${r.agent}: ${pc.dim(r.error)}`);
}
}
console.log();
p.outro(
pc.green('Done!') +
pc.dim(' Review skills before use; they run with full agent permissions.')
);
// Prompt for find-skills after successful install
await promptForFindSkills(options, targetAgents);
} catch (error) {
if (error instanceof GitCloneError) {
p.log.error(pc.red('Failed to clone repository'));
// Print each line of the error message separately for better formatting
for (const line of error.message.split('\n')) {
p.log.message(pc.dim(line));
}
} else {
p.log.error(error instanceof Error ? error.message : 'Unknown error occurred');
}
showInstallTip();
p.outro(pc.red('Installation failed'));
process.exit(1);
} finally {
await cleanup(tempDir);
}
}
// Cleanup helper
async function cleanup(tempDir: string | null) {
if (tempDir) {
try {
await cleanupTempDir(tempDir);
} catch {
// Ignore cleanup errors
}
}
}
/**
* Prompt user to install the find-skills skill after their first installation.
*/
async function promptForFindSkills(
options?: AddOptions,
targetAgents?: AgentType[]
): Promise<void> {
// Skip if already dismissed or not in interactive mode
if (!process.stdin.isTTY) return;
if (options?.yes) return;
try {
const dismissed = await isPromptDismissed('findSkillsPrompt');
if (dismissed) return;
// Check if find-skills is already installed
const findSkillsInstalled = await isSkillInstalled('find-skills', 'claude-code', {
global: true,
});
if (findSkillsInstalled) {
// Mark as dismissed so we don't check again
await dismissPrompt('findSkillsPrompt');
return;
}
console.log();
p.log.message(pc.dim("One-time prompt - you won't be asked again if you dismiss."));
const install = await p.confirm({
message: `Install the ${pc.cyan('find-skills')} skill? It helps your agent discover and suggest skills.`,
});
if (p.isCancel(install)) {
await dismissPrompt('findSkillsPrompt');
return;
}
if (install) {
// Install find-skills to the same agents the user selected, excluding replit
await dismissPrompt('findSkillsPrompt');
// Filter out replit from target agents
const findSkillsAgents = targetAgents?.filter((a) => a !== 'replit');
// Skip if no valid agents remain after filtering
if (!findSkillsAgents || findSkillsAgents.length === 0) {
return;
}
console.log();
p.log.step('Installing find-skills skill...');
try {
// Call runAdd directly
await runAdd(['vercel-labs/skills'], {
skill: ['find-skills'],
global: true,
yes: true,
agent: findSkillsAgents,
});
} catch {
p.log.warn('Failed to install find-skills. You can try again with:');
p.log.message(pc.dim(' npx skills add vercel-labs/skills@find-skills -g -y --all'));
}
} else {
// User declined - dismiss the prompt
await dismissPrompt('findSkillsPrompt');
p.log.message(
pc.dim('You can install it later with: npx skills add vercel-labs/skills@find-skills')
);
}
} catch {
// Don't fail the main installation if prompt fails
}
}
// Parse command line options from args array
export function parseAddOptions(args: string[]): { source: string[]; options: AddOptions } {
const options: AddOptions = {};
const source: string[] = [];
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '-g' || arg === '--global') {
options.global = true;
} else if (arg === '-y' || arg === '--yes') {
options.yes = true;
} else if (arg === '-l' || arg === '--list') {
options.list = true;
} else if (arg === '--all') {
options.all = true;
} else if (arg === '-a' || arg === '--agent') {
options.agent = options.agent || [];
i++;
let nextArg = args[i];
while (i < args.length && nextArg && !nextArg.startsWith('-')) {
options.agent.push(nextArg);
i++;
nextArg = args[i];
}
i--; // Back up one since the loop will increment
} else if (arg === '-s' || arg === '--skill') {
options.skill = options.skill || [];
i++;
let nextArg = args[i];
while (i < args.length && nextArg && !nextArg.startsWith('-')) {
options.skill.push(nextArg);
i++;
nextArg = args[i];
}
i--; // Back up one since the loop will increment
} else if (arg === '--full-depth') {
options.fullDepth = true;
} else if (arg === '--copy') {
options.copy = true;
} else if (arg && !arg.startsWith('-')) {
source.push(arg);
}
}
return { source, options };
}
================================================
FILE: src/agents.ts
================================================
import { homedir } from 'os';
import { join } from 'path';
import { existsSync } from 'fs';
import { xdgConfig } from 'xdg-basedir';
import type { AgentConfig, AgentType } from './types.ts';
const home = homedir();
// Use xdg-basedir (not env-paths) to match OpenCode/Amp/Goose behavior on all platforms.
const configHome = xdgConfig ?? join(home, '.config');
const codexHome = process.env.CODEX_HOME?.trim() || join(home, '.codex');
const claudeHome = process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, '.claude');
export function getOpenClawGlobalSkillsDir(
homeDir = home,
pathExists: (path: string) => boolean = existsSync
) {
if (pathExists(join(homeDir, '.openclaw'))) {
return join(homeDir, '.openclaw/skills');
}
if (pathExists(join(homeDir, '.clawdbot'))) {
return join(homeDir, '.clawdbot/skills');
}
if (pathExists(join(homeDir, '.moltbot'))) {
return join(homeDir, '.moltbot/skills');
}
return join(homeDir, '.openclaw/skills');
}
export const agents: Record<AgentType, AgentConfig> = {
amp: {
name: 'amp',
displayName: 'Amp',
skillsDir: '.agents/skills',
globalSkillsDir: join(configHome, 'agents/skills'),
detectInstalled: async () => {
return existsSync(join(configHome, 'amp'));
},
},
antigravity: {
name: 'antigravity',
displayName: 'Antigravity',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.gemini/antigravity/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.gemini/antigravity'));
},
},
augment: {
name: 'augment',
displayName: 'Augment',
skillsDir: '.augment/skills',
globalSkillsDir: join(home, '.augment/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.augment'));
},
},
'claude-code': {
name: 'claude-code',
displayName: 'Claude Code',
skillsDir: '.claude/skills',
globalSkillsDir: join(claudeHome, 'skills'),
detectInstalled: async () => {
return existsSync(claudeHome);
},
},
openclaw: {
name: 'openclaw',
displayName: 'OpenClaw',
skillsDir: 'skills',
globalSkillsDir: getOpenClawGlobalSkillsDir(),
detectInstalled: async () => {
return (
existsSync(join(home, '.openclaw')) ||
existsSync(join(home, '.clawdbot')) ||
existsSync(join(home, '.moltbot'))
);
},
},
cline: {
name: 'cline',
displayName: 'Cline',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.agents', 'skills'),
detectInstalled: async () => {
return existsSync(join(home, '.cline'));
},
},
codebuddy: {
name: 'codebuddy',
displayName: 'CodeBuddy',
skillsDir: '.codebuddy/skills',
globalSkillsDir: join(home, '.codebuddy/skills'),
detectInstalled: async () => {
return existsSync(join(process.cwd(), '.codebuddy')) || existsSync(join(home, '.codebuddy'));
},
},
codex: {
name: 'codex',
displayName: 'Codex',
skillsDir: '.agents/skills',
globalSkillsDir: join(codexHome, 'skills'),
detectInstalled: async () => {
return existsSync(codexHome) || existsSync('/etc/codex');
},
},
'command-code': {
name: 'command-code',
displayName: 'Command Code',
skillsDir: '.commandcode/skills',
globalSkillsDir: join(home, '.commandcode/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.commandcode'));
},
},
continue: {
name: 'continue',
displayName: 'Continue',
skillsDir: '.continue/skills',
globalSkillsDir: join(home, '.continue/skills'),
detectInstalled: async () => {
return existsSync(join(process.cwd(), '.continue')) || existsSync(join(home, '.continue'));
},
},
cortex: {
name: 'cortex',
displayName: 'Cortex Code',
skillsDir: '.cortex/skills',
globalSkillsDir: join(home, '.snowflake/cortex/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.snowflake/cortex'));
},
},
crush: {
name: 'crush',
displayName: 'Crush',
skillsDir: '.crush/skills',
globalSkillsDir: join(home, '.config/crush/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.config/crush'));
},
},
cursor: {
name: 'cursor',
displayName: 'Cursor',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.cursor/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.cursor'));
},
},
deepagents: {
name: 'deepagents',
displayName: 'Deep Agents',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.deepagents/agent/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.deepagents'));
},
},
droid: {
name: 'droid',
displayName: 'Droid',
skillsDir: '.factory/skills',
globalSkillsDir: join(home, '.factory/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.factory'));
},
},
'gemini-cli': {
name: 'gemini-cli',
displayName: 'Gemini CLI',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.gemini/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.gemini'));
},
},
'github-copilot': {
name: 'github-copilot',
displayName: 'GitHub Copilot',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.copilot/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.copilot'));
},
},
goose: {
name: 'goose',
displayName: 'Goose',
skillsDir: '.goose/skills',
globalSkillsDir: join(configHome, 'goose/skills'),
detectInstalled: async () => {
return existsSync(join(configHome, 'goose'));
},
},
junie: {
name: 'junie',
displayName: 'Junie',
skillsDir: '.junie/skills',
globalSkillsDir: join(home, '.junie/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.junie'));
},
},
'iflow-cli': {
name: 'iflow-cli',
displayName: 'iFlow CLI',
skillsDir: '.iflow/skills',
globalSkillsDir: join(home, '.iflow/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.iflow'));
},
},
kilo: {
name: 'kilo',
displayName: 'Kilo Code',
skillsDir: '.kilocode/skills',
globalSkillsDir: join(home, '.kilocode/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.kilocode'));
},
},
'kimi-cli': {
name: 'kimi-cli',
displayName: 'Kimi Code CLI',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.config/agents/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.kimi'));
},
},
'kiro-cli': {
name: 'kiro-cli',
displayName: 'Kiro CLI',
skillsDir: '.kiro/skills',
globalSkillsDir: join(home, '.kiro/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.kiro'));
},
},
kode: {
name: 'kode',
displayName: 'Kode',
skillsDir: '.kode/skills',
globalSkillsDir: join(home, '.kode/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.kode'));
},
},
mcpjam: {
name: 'mcpjam',
displayName: 'MCPJam',
skillsDir: '.mcpjam/skills',
globalSkillsDir: join(home, '.mcpjam/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.mcpjam'));
},
},
'mistral-vibe': {
name: 'mistral-vibe',
displayName: 'Mistral Vibe',
skillsDir: '.vibe/skills',
globalSkillsDir: join(home, '.vibe/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.vibe'));
},
},
mux: {
name: 'mux',
displayName: 'Mux',
skillsDir: '.mux/skills',
globalSkillsDir: join(home, '.mux/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.mux'));
},
},
opencode: {
name: 'opencode',
displayName: 'OpenCode',
skillsDir: '.agents/skills',
globalSkillsDir: join(configHome, 'opencode/skills'),
detectInstalled: async () => {
return existsSync(join(configHome, 'opencode'));
},
},
openhands: {
name: 'openhands',
displayName: 'OpenHands',
skillsDir: '.openhands/skills',
globalSkillsDir: join(home, '.openhands/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.openhands'));
},
},
pi: {
name: 'pi',
displayName: 'Pi',
skillsDir: '.pi/skills',
globalSkillsDir: join(home, '.pi/agent/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.pi/agent'));
},
},
qoder: {
name: 'qoder',
displayName: 'Qoder',
skillsDir: '.qoder/skills',
globalSkillsDir: join(home, '.qoder/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.qoder'));
},
},
'qwen-code': {
name: 'qwen-code',
displayName: 'Qwen Code',
skillsDir: '.qwen/skills',
globalSkillsDir: join(home, '.qwen/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.qwen'));
},
},
replit: {
name: 'replit',
displayName: 'Replit',
skillsDir: '.agents/skills',
globalSkillsDir: join(configHome, 'agents/skills'),
showInUniversalList: false,
detectInstalled: async () => {
return existsSync(join(process.cwd(), '.replit'));
},
},
roo: {
name: 'roo',
displayName: 'Roo Code',
skillsDir: '.roo/skills',
globalSkillsDir: join(home, '.roo/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.roo'));
},
},
trae: {
name: 'trae',
displayName: 'Trae',
skillsDir: '.trae/skills',
globalSkillsDir: join(home, '.trae/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.trae'));
},
},
'trae-cn': {
name: 'trae-cn',
displayName: 'Trae CN',
skillsDir: '.trae/skills',
globalSkillsDir: join(home, '.trae-cn/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.trae-cn'));
},
},
warp: {
name: 'warp',
displayName: 'Warp',
skillsDir: '.agents/skills',
globalSkillsDir: join(home, '.agents/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.warp'));
},
},
windsurf: {
name: 'windsurf',
displayName: 'Windsurf',
skillsDir: '.windsurf/skills',
globalSkillsDir: join(home, '.codeium/windsurf/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.codeium/windsurf'));
},
},
zencoder: {
name: 'zencoder',
displayName: 'Zencoder',
skillsDir: '.zencoder/skills',
globalSkillsDir: join(home, '.zencoder/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.zencoder'));
},
},
neovate: {
name: 'neovate',
displayName: 'Neovate',
skillsDir: '.neovate/skills',
globalSkillsDir: join(home, '.neovate/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.neovate'));
},
},
pochi: {
name: 'pochi',
displayName: 'Pochi',
skillsDir: '.pochi/skills',
globalSkillsDir: join(home, '.pochi/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.pochi'));
},
},
adal: {
name: 'adal',
displayName: 'AdaL',
skillsDir: '.adal/skills',
globalSkillsDir: join(home, '.adal/skills'),
detectInstalled: async () => {
return existsSync(join(home, '.adal'));
},
},
universal: {
name: 'universal',
displayName: 'Universal',
skillsDir: '.agents/skills',
globalSkillsDir: join(configHome, 'agents/skills'),
showInUniversalList: false,
detectInstalled: async () => false,
},
};
export async function detectInstalledAgents(): Promise<AgentType[]> {
const results = await Promise.all(
Object.entries(agents).map(async ([type, config]) => ({
type: type as AgentType,
installed: await config.detectInstalled(),
}))
);
return results.filter((r) => r.installed).map((r) => r.type);
}
export function getAgentConfig(type: AgentType): AgentConfig {
return agents[type];
}
/**
* Returns agents that use the universal .agents/skills directory.
* These agents share a common skill location and don't need symlinks.
* Agents with showInUniversalList: false are excluded.
*/
export function getUniversalAgents(): AgentType[] {
return (Object.entries(agents) as [AgentType, AgentConfig][])
.filter(
([_, config]) => config.skillsDir === '.agents/skills' && config.showInUniversalList !== false
)
.map(([type]) => type);
}
/**
* Returns agents that use agent-specific skill directories (not universal).
* These agents need symlinks from the canonical .agents/skills location.
*/
export function getNonUniversalAgents(): AgentType[] {
return (Object.entries(agents) as [AgentType, AgentConfig][])
.filter(([_, config]) => config.skillsDir !== '.agents/skills')
.map(([type]) => type);
}
/**
* Check if an agent uses the universal .agents/skills directory.
*/
export function isUniversalAgent(type: AgentType): boolean {
return agents[type].skillsDir === '.agents/skills';
}
================================================
FILE: src/cli.test.ts
================================================
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { join } from 'path';
import { runCliOutput, stripLogo, hasLogo } from './test-utils.ts';
describe('skills CLI', () => {
describe('--help', () => {
it('should display help message', () => {
const output = runCliOutput(['--help']);
expect(output).toContain('Usage: skills <command> [options]');
expect(output).toContain('Manage Skills:');
expect(output).toContain('init [name]');
expect(output).toContain('add <package>');
expect(output).toContain('check');
expect(output).toContain('update');
expect(output).toContain('Add Options:');
expect(output).toContain('-g, --global');
expect(output).toContain('-a, --agent');
expect(output).toContain('-s, --skill');
expect(output).toContain('-l, --list');
expect(output).toContain('-y, --yes');
expect(output).toContain('--all');
});
it('should show same output for -h alias', () => {
const helpOutput = runCliOutput(['--help']);
const hOutput = runCliOutput(['-h']);
expect(hOutput).toBe(helpOutput);
});
});
describe('--version', () => {
it('should display version number', () => {
const output = runCliOutput(['--version']);
expect(output.trim()).toMatch(/^\d+\.\d+\.\d+$/);
});
it('should match package.json version', () => {
const output = runCliOutput(['--version']);
const pkg = JSON.parse(
readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf-8')
);
expect(output.trim()).toBe(pkg.version);
});
});
describe('no arguments', () => {
it('should display banner', () => {
const output = stripLogo(runCliOutput([]));
expect(output).toContain('The open agent skills ecosystem');
expect(output).toContain('npx skills add');
expect(output).toContain('npx skills check');
expect(output).toContain('npx skills update');
expect(output).toContain('npx skills init');
expect(output).toContain('skills.sh');
});
});
describe('unknown command', () => {
it('should show error for unknown command', () => {
const output = runCliOutput(['unknown-command']);
expect(output).toMatchInlineSnapshot(`
"Unknown command: unknown-command
Run skills --help for usage.
"
`);
});
});
describe('logo display', () => {
it('should not display logo for list command', () => {
const output = runCliOutput(['list']);
expect(hasLogo(output)).toBe(false);
});
it('should not display logo for check command', () => {
// Note: check command makes GitHub API calls, so we just verify initial output
const output = runCliOutput(['check']);
expect(hasLogo(output)).toBe(false);
}, 60000);
it('should not display logo for update command', () => {
// Note: update command makes GitHub API calls, so we just verify initial output
const output = runCliOutput(['update']);
expect(hasLogo(output)).toBe(false);
}, 60000);
});
});
================================================
FILE: src/cli.ts
================================================
#!/usr/bin/env node
import { spawnSync } from 'child_process';
import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
import { basename, join, dirname } from 'path';
import { homedir } from 'os';
import { fileURLToPath } from 'url';
import { runAdd, parseAddOptions, initTelemetry } from './add.ts';
import { runFind } from './find.ts';
import { runInstallFromLock } from './install.ts';
import { runList } from './list.ts';
import { removeCommand, parseRemoveOptions } from './remove.ts';
import { runSync, parseSyncOptions } from './sync.ts';
import { track } from './telemetry.ts';
import { fetchSkillFolderHash, getGitHubToken } from './skill-lock.ts';
const __dirname = dirname(fileURLToPath(import.meta.url));
function getVersion(): string {
try {
const pkgPath = join(__dirname, '..', 'package.json');
const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
return pkg.version;
} catch {
return '0.0.0';
}
}
const VERSION = getVersion();
initTelemetry(VERSION);
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';
// 256-color grays - visible on both light and dark backgrounds
const DIM = '\x1b[38;5;102m'; // darker gray for secondary text
const TEXT = '\x1b[38;5;145m'; // lighter gray for primary text
const LOGO_LINES = [
'███████╗██╗ ██╗██╗██╗ ██╗ ███████╗',
'██╔════╝██║ ██╔╝██║██║ ██║ ██╔════╝',
'███████╗█████╔╝ ██║██║ ██║ ███████╗',
'╚════██║██╔═██╗ ██║██║ ██║ ╚════██║',
'███████║██║ ██╗██║███████╗███████╗███████║',
'╚══════╝╚═╝ ╚═╝╚═╝╚══════╝╚══════╝╚══════╝',
];
// 256-color middle grays - visible on both light and dark backgrounds
const GRAYS = [
'\x1b[38;5;250m', // lighter gray
'\x1b[38;5;248m',
'\x1b[38;5;245m', // mid gray
'\x1b[38;5;243m',
'\x1b[38;5;240m',
'\x1b[38;5;238m', // darker gray
];
function showLogo(): void {
console.log();
LOGO_LINES.forEach((line, i) => {
console.log(`${GRAYS[i]}${line}${RESET}`);
});
}
function showBanner(): void {
showLogo();
console.log();
console.log(`${DIM}The open agent skills ecosystem${RESET}`);
console.log();
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills add ${DIM}<package>${RESET} ${DIM}Add a new skill${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills remove${RESET} ${DIM}Remove installed skills${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills list${RESET} ${DIM}List installed skills${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills find ${DIM}[query]${RESET} ${DIM}Search for skills${RESET}`
);
console.log();
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills check${RESET} ${DIM}Check for updates${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills update${RESET} ${DIM}Update all skills${RESET}`
);
console.log();
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills experimental_install${RESET} ${DIM}Restore from skills-lock.json${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills init ${DIM}[name]${RESET} ${DIM}Create a new skill${RESET}`
);
console.log(
` ${DIM}$${RESET} ${TEXT}npx skills experimental_sync${RESET} ${DIM}Sync skills from node_modules${RESET}`
);
console.log();
console.log(`${DIM}try:${RESET} npx skills add vercel-labs/agent-skills`);
console.log();
console.log(`Discover more skills at ${TEXT}https://skills.sh/${RESET}`);
console.log();
}
function showHelp(): void {
console.log(`
${BOLD}Usage:${RESET} skills <command> [options]
${BOLD}Manage Skills:${RESET}
add <package> Add a skill package (alias: a)
e.g. vercel-labs/agent-skills
https://github.com/vercel-labs/agent-skills
remove [skills] Remove installed skills
list, ls List installed skills
find [query] Search for skills interactively
${BOLD}Updates:${RESET}
check Check for available skill updates
update Update all skills to latest versions
${BOLD}Project:${RESET}
experimental_install Restore skills from skills-lock.json
init [name] Initialize a skill (creates <name>/SKILL.md or ./SKILL.md)
experimental_sync Sync skills from node_modules into agent directories
${BOLD}Add Options:${RESET}
-g, --global Install skill globally (user-level) instead of project-level
-a, --agent <agents> Specify agents to install to (use '*' for all agents)
-s, --skill <skills> Specify skill names to install (use '*' for all skills)
-l, --list List available skills in the repository without installing
-y, --yes Skip confirmation prompts
--copy Copy files instead of symlinking to agent directories
--all Shorthand for --skill '*' --agent '*' -y
--full-depth Search all subdirectories even when a root SKILL.md exists
${BOLD}Remove Options:${RESET}
-g, --global Remove from global scope
-a, --agent <agents> Remove from specific agents (use '*' for all agents)
-s, --skill <skills> Specify skills to remove (use '*' for all skills)
-y, --yes Skip confirmation prompts
--all Shorthand for --skill '*' --agent '*' -y
${BOLD}Experimental Sync Options:${RESET}
-a, --agent <agents> Specify agents to install to (use '*' for all agents)
-y, --yes Skip confirmation prompts
${BOLD}List Options:${RESET}
-g, --global List global skills (default: project)
-a, --agent <agents> Filter by specific agents
--json Output as JSON (machine-readable, no ANSI codes)
${BOLD}Options:${RESET}
--help, -h Show this help message
--version, -v Show version number
${BOLD}Examples:${RESET}
${DIM}$${RESET} skills add vercel-labs/agent-skills
${DIM}$${RESET} skills add vercel-labs/agent-skills -g
${DIM}$${RESET} skills add vercel-labs/agent-skills --agent claude-code cursor
${DIM}$${RESET} skills add vercel-labs/agent-skills --skill pr-review commit
${DIM}$${RESET} skills remove ${DIM}# interactive remove${RESET}
${DIM}$${RESET} skills remove web-design ${DIM}# remove by name${RESET}
${DIM}$${RESET} skills rm --global frontend-design
${DIM}$${RESET} skills list ${DIM}# list project skills${RESET}
${DIM}$${RESET} skills ls -g ${DIM}# list global skills${RESET}
${DIM}$${RESET} skills ls -a claude-code ${DIM}# filter by agent${RESET}
${DIM}$${RESET} skills ls --json ${DIM}# JSON output${RESET}
${DIM}$${RESET} skills find ${DIM}# interactive search${RESET}
${DIM}$${RESET} skills find typescript ${DIM}# search by keyword${RESET}
${DIM}$${RESET} skills check
${DIM}$${RESET} skills update
${DIM}$${RESET} skills experimental_install ${DIM}# restore from skills-lock.json${RESET}
${DIM}$${RESET} skills init my-skill
${DIM}$${RESET} skills experimental_sync ${DIM}# sync from node_modules${RESET}
${DIM}$${RESET} skills experimental_sync -y ${DIM}# sync without prompts${RESET}
Discover more skills at ${TEXT}https://skills.sh/${RESET}
`);
}
function showRemoveHelp(): void {
console.log(`
${BOLD}Usage:${RESET} skills remove [skills...] [options]
${BOLD}Description:${RESET}
Remove installed skills from agents. If no skill names are provided,
an interactive selection menu will be shown.
${BOLD}Arguments:${RESET}
skills Optional skill names to remove (space-separated)
${BOLD}Options:${RESET}
-g, --global Remove from global scope (~/) instead of project scope
-a, --agent Remove from specific agents (use '*' for all agents)
-s, --skill Specify skills to remove (use '*' for all skills)
-y, --yes Skip confirmation prompts
--all Shorthand for --skill '*' --agent '*' -y
${BOLD}Examples:${RESET}
${DIM}$${RESET} skills remove ${DIM}# interactive selection${RESET}
${DIM}$${RESET} skills remove my-skill ${DIM}# remove specific skill${RESET}
${DIM}$${RESET} skills remove skill1 skill2 -y ${DIM}# remove multiple skills${RESET}
${DIM}$${RESET} skills remove --global my-skill ${DIM}# remove from global scope${RESET}
${DIM}$${RESET} skills rm --agent claude-code my-skill ${DIM}# remove from specific agent${RESET}
${DIM}$${RESET} skills remove --all ${DIM}# remove all skills${RESET}
${DIM}$${RESET} skills remove --skill '*' -a cursor ${DIM}# remove all skills from cursor${RESET}
Discover more skills at ${TEXT}https://skills.sh/${RESET}
`);
}
function runInit(args: string[]): void {
const cwd = process.cwd();
const skillName = args[0] || basename(cwd);
const hasName = args[0] !== undefined;
const skillDir = hasName ? join(cwd, skillName) : cwd;
const skillFile = join(skillDir, 'SKILL.md');
const displayPath = hasName ? `${skillName}/SKILL.md` : 'SKILL.md';
if (existsSync(skillFile)) {
console.log(`${TEXT}Skill already exists at ${DIM}${displayPath}${RESET}`);
return;
}
if (hasName) {
mkdirSync(skillDir, { recursive: true });
}
const skillContent = `---
name: ${skillName}
description: A brief description of what this skill does
---
# ${skillName}
Instructions for the agent to follow when this skill is activated.
## When to use
Describe when this skill should be used.
## Instructions
1. First step
2. Second step
3. Additional steps as needed
`;
writeFileSync(skillFile, skillContent);
console.log(`${TEXT}Initialized skill: ${DIM}${skillName}${RESET}`);
console.log();
console.log(`${DIM}Created:${RESET}`);
console.log(` ${displayPath}`);
console.log();
console.log(`${DIM}Next steps:${RESET}`);
console.log(` 1. Edit ${TEXT}${displayPath}${RESET} to define your skill instructions`);
console.log(
` 2. Update the ${TEXT}name${RESET} and ${TEXT}description${RESET} in the frontmatter`
);
console.log();
console.log(`${DIM}Publishing:${RESET}`);
console.log(
` ${DIM}GitHub:${RESET} Push to a repo, then ${TEXT}npx skills add <owner>/<repo>${RESET}`
);
console.log(
` ${DIM}URL:${RESET} Host the file, then ${TEXT}npx skills add https://example.com/${displayPath}${RESET}`
);
console.log();
console.log(`Browse existing skills for inspiration at ${TEXT}https://skills.sh/${RESET}`);
console.log();
}
// ============================================
// Check and Update Commands
// ============================================
const AGENTS_DIR = '.agents';
const LOCK_FILE = '.skill-lock.json';
const CURRENT_LOCK_VERSION = 3; // Bumped from 2 to 3 for folder hash support
interface SkillLockEntry {
source: string;
sourceType: string;
sourceUrl: string;
skillPath?: string;
/** GitHub tree SHA for the entire skill folder (v3) */
skillFolderHash: string;
installedAt: string;
updatedAt: string;
}
interface SkillLockFile {
version: number;
skills: Record<string, SkillLockEntry>;
}
function getSkillLockPath(): string {
const xdgStateHome = process.env.XDG_STATE_HOME;
if (xdgStateHome) {
return join(xdgStateHome, 'skills', LOCK_FILE);
}
return join(homedir(), AGENTS_DIR, LOCK_FILE);
}
function readSkillLock(): SkillLockFile {
const lockPath = getSkillLockPath();
try {
const content = readFileSync(lockPath, 'utf-8');
const parsed = JSON.parse(content) as SkillLockFile;
if (typeof parsed.version !== 'number' || !parsed.skills) {
return { version: CURRENT_LOCK_VERSION, skills: {} };
}
// If old version, wipe and start fresh (backwards incompatible change)
// v3 adds skillFolderHash - we want fresh installs to populate it
if (parsed.version < CURRENT_LOCK_VERSION) {
return { version: CURRENT_LOCK_VERSION, skills: {} };
}
return parsed;
} catch {
return { version: CURRENT_LOCK_VERSION, skills: {} };
}
}
interface SkippedSkill {
name: string;
reason: string;
sourceUrl: string;
}
/**
* Determine why a skill cannot be checked for updates automatically.
*/
function getSkipReason(entry: SkillLockEntry): string {
if (entry.sourceType === 'local') {
return 'Local path';
}
if (entry.sourceType === 'git') {
return 'Git URL (hash tracking not supported)';
}
if (!entry.skillFolderHash) {
return 'No version hash available';
}
if (!entry.skillPath) {
return 'No skill path recorded';
}
return 'No version tracking';
}
/**
* Print a list of skills that cannot be checked automatically,
* with the reason and a manual update command for each.
*/
function printSkippedSkills(skipped: SkippedSkill[]): void {
if (skipped.length === 0) return;
console.log();
console.log(`${DIM}${skipped.length} skill(s) cannot be checked automatically:${RESET}`);
for (const skill of skipped) {
console.log(` ${TEXT}•${RESET} ${skill.name} ${DIM}(${skill.reason})${RESET}`);
console.log(` ${DIM}To update: ${TEXT}npx skills add ${skill.sourceUrl} -g -y${RESET}`);
}
}
async function runCheck(args: string[] = []): Promise<void> {
console.log(`${TEXT}Checking for skill updates...${RESET}`);
console.log();
const lock = readSkillLock();
const skillNames = Object.keys(lock.skills);
if (skillNames.length === 0) {
console.log(`${DIM}No skills tracked in lock file.${RESET}`);
console.log(`${DIM}Install skills with${RESET} ${TEXT}npx skills add <package>${RESET}`);
return;
}
// Get GitHub token from user's environment for higher rate limits
const token = getGitHubToken();
// Group skills by source (owner/repo) to batch GitHub API calls
const skillsBySource = new Map<string, Array<{ name: string; entry: SkillLockEntry }>>();
const skipped: SkippedSkill[] = [];
for (const skillName of skillNames) {
const entry = lock.skills[skillName];
if (!entry) continue;
// Only check skills with folder hash and skill path
if (!entry.skillFolderHash || !entry.skillPath) {
skipped.push({ name: skillName, reason: getSkipReason(entry), sourceUrl: entry.sourceUrl });
continue;
}
const existing = skillsBySource.get(entry.source) || [];
existing.push({ name: skillName, entry });
skillsBySource.set(entry.source, existing);
}
const totalSkills = skillNames.length - skipped.length;
if (totalSkills === 0) {
console.log(`${DIM}No GitHub skills to check.${RESET}`);
printSkippedSkills(skipped);
return;
}
console.log(`${DIM}Checking ${totalSkills} skill(s) for updates...${RESET}`);
const updates: Array<{ name: string; source: string }> = [];
const errors: Array<{ name: string; source: string; error: string }> = [];
// Check each source (one API call per repo)
for (const [source, skills] of skillsBySource) {
for (const { name, entry } of skills) {
try {
const latestHash = await fetchSkillFolderHash(source, entry.skillPath!, token);
if (!latestHash) {
errors.push({ name, source, error: 'Could not fetch from GitHub' });
continue;
}
if (latestHash !== entry.skillFolderHash) {
updates.push({ name, source });
}
} catch (err) {
errors.push({
name,
source,
error: err instanceof Error ? err.message : 'Unknown error',
});
}
}
}
console.log();
if (updates.length === 0) {
console.log(`${TEXT}✓ All skills are up to date${RESET}`);
} else {
console.log(`${TEXT}${updates.length} update(s) available:${RESET}`);
console.log();
for (const update of updates) {
console.log(` ${TEXT}↑${RESET} ${update.name}`);
console.log(` ${DIM}source: ${update.source}${RESET}`);
}
console.log();
console.log(
`${DIM}Run${RESET} ${TEXT}npx skills update${RESET} ${DIM}to update all skills${RESET}`
);
}
if (errors.length > 0) {
console.log();
console.log(`${DIM}Could not check ${errors.length} skill(s) (may need reinstall)${RESET}`);
console.log();
for (const error of errors) {
console.log(` ${DIM}✗${RESET} ${error.name}`);
console.log(` ${DIM}source: ${error.source}${RESET}`);
}
}
printSkippedSkills(skipped);
// Track telemetry
track({
event: 'check',
skillCount: String(totalSkills),
updatesAvailable: String(updates.length),
});
console.log();
}
async function runUpdate(): Promise<void> {
console.log(`${TEXT}Checking for skill updates...${RESET}`);
console.log();
const lock = readSkillLock();
const skillNames = Object.keys(lock.skills);
if (skillNames.length === 0) {
console.log(`${DIM}No skills tracked in lock file.${RESET}`);
console.log(`${DIM}Install skills with${RESET} ${TEXT}npx skills add <package>${RESET}`);
return;
}
// Get GitHub token from user's environment for higher rate limits
const token = getGitHubToken();
// Find skills that need updates by checking GitHub directly
const updates: Array<{ name: string; source: string; entry: SkillLockEntry }> = [];
const skipped: SkippedSkill[] = [];
for (const skillName of skillNames) {
const entry = lock.skills[skillName];
if (!entry) continue;
// Only check skills with folder hash and skill path
if (!entry.skillFolderHash || !entry.skillPath) {
skipped.push({ name: skillName, reason: getSkipReason(entry), sourceUrl: entry.sourceUrl });
continue;
}
try {
const latestHash = await fetchSkillFolderHash(entry.source, entry.skillPath, token);
if (latestHash && latestHash !== entry.skillFolderHash) {
updates.push({ name: skillName, source: entry.source, entry });
}
} catch {
// Skip skills that fail to check
}
}
const checkedCount = skillNames.length - skipped.length;
if (checkedCount === 0) {
console.log(`${DIM}No skills to check.${RESET}`);
printSkippedSkills(skipped);
return;
}
if (updates.length === 0) {
console.log(`${TEXT}✓ All skills are up to date${RESET}`);
console.log();
return;
}
console.log(`${TEXT}Found ${updates.length} update(s)${RESET}`);
console.log();
// Reinstall each skill that has an update
let successCount = 0;
let failCount = 0;
for (const update of updates) {
console.log(`${TEXT}Updating ${update.name}...${RESET}`);
// Build the URL with subpath to target the specific skill directory
// e.g., https://github.com/owner/repo/tree/main/skills/my-skill
let installUrl = update.entry.sourceUrl;
if (update.entry.skillPath) {
// Extract the skill folder path (remove /SKILL.md suffix)
let skillFolder = update.entry.skillPath;
if (skillFolder.endsWith('/SKILL.md')) {
skillFolder = skillFolder.slice(0, -9);
} else if (skillFolder.endsWith('SKILL.md')) {
skillFolder = skillFolder.slice(0, -8);
}
if (skillFolder.endsWith('/')) {
skillFolder = skillFolder.slice(0, -1);
}
// Convert git URL to tree URL with path
// https://github.com/owner/repo.git -> https://github.com/owner/repo/tree/main/path
installUrl = update.entry.sourceUrl.replace(/\.git$/, '').replace(/\/$/, '');
installUrl = `${installUrl}/tree/main/${skillFolder}`;
}
// Reinstall using the current CLI entrypoint directly (avoid nested npm exec/npx)
const cliEntry = join(__dirname, '..', 'bin', 'cli.mjs');
if (!existsSync(cliEntry)) {
failCount++;
console.log(
` ${DIM}✗ Failed to update ${update.name}: CLI entrypoint not found at ${cliEntry}${RESET}`
);
continue;
}
const result = spawnSync(process.execPath, [cliEntry, 'add', installUrl, '-g', '-y'], {
stdio: ['inherit', 'pipe', 'pipe'],
encoding: 'utf-8',
shell: process.platform === 'win32',
});
if (result.status === 0) {
successCount++;
console.log(` ${TEXT}✓${RESET} Updated ${update.name}`);
} else {
failCount++;
console.log(` ${DIM}✗ Failed to update ${update.name}${RESET}`);
}
}
console.log();
if (successCount > 0) {
console.log(`${TEXT}✓ Updated ${successCount} skill(s)${RESET}`);
}
if (failCount > 0) {
console.log(`${DIM}Failed to update ${failCount} skill(s)${RESET}`);
}
// Track telemetry
track({
event: 'update',
skillCount: String(updates.length),
successCount: String(successCount),
failCount: String(failCount),
});
console.log();
}
// ============================================
// Main
// ============================================
async function main(): Promise<void> {
const args = process.argv.slice(2);
if (args.length === 0) {
showBanner();
return;
}
const command = args[0];
const restArgs = args.slice(1);
switch (command) {
case 'find':
case 'search':
case 'f':
case 's':
showLogo();
console.log();
await runFind(restArgs);
break;
case 'init':
showLogo();
console.log();
runInit(restArgs);
break;
case 'experimental_install': {
showLogo();
await runInstallFromLock(restArgs);
break;
}
case 'i':
case 'install':
case 'a':
case 'add': {
showLogo();
const { source: addSource, options: addOpts } = parseAddOptions(restArgs);
await runAdd(addSource, addOpts);
break;
}
case 'remove':
case 'rm':
case 'r':
// Check for --help or -h flag
if (restArgs.includes('--help') || restArgs.includes('-h')) {
showRemoveHelp();
break;
}
const { skills, options: removeOptions } = parseRemoveOptions(restArgs);
await removeCommand(skills, removeOptions);
break;
case 'experimental_sync': {
showLogo();
const { options: syncOptions } = parseSyncOptions(restArgs);
await runSync(restArgs, syncOptions);
break;
}
case 'list':
case 'ls':
await runList(restArgs);
break;
case 'check':
runCheck(restArgs);
break;
case 'update':
case 'upgrade':
runUpdate();
break;
case '--help':
case '-h':
showHelp();
break;
case '--version':
case '-v':
console.log(VERSION);
break;
default:
console.log(`Unknown command: ${command}`);
console.log(`Run ${BOLD}skills --help${RESET} for usage.`);
}
}
main();
================================================
FILE: src/constants.ts
================================================
export const AGENTS_DIR = '.agents';
export const SKILLS_SUBDIR = 'skills';
export const UNIVERSAL_SKILLS_DIR = '.agents/skills';
================================================
FILE: src/find.ts
================================================
import * as readline from 'readline';
import { runAdd, parseAddOptions } from './add.ts';
import { track } from './telemetry.ts';
import { isRepoPrivate } from './source-parser.ts';
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';
const DIM = '\x1b[38;5;102m';
const TEXT = '\x1b[38;5;145m';
const CYAN = '\x1b[36m';
const MAGENTA = '\x1b[35m';
const YELLOW = '\x1b[33m';
// API endpoint for skills search
const SEARCH_API_BASE = process.env.SKILLS_API_URL || 'https://skills.sh';
function formatInstalls(count: number): string {
if (!count || count <= 0) return '';
if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, '')}M installs`;
if (count >= 1_000) return `${(count / 1_000).toFixed(1).replace(/\.0$/, '')}K installs`;
return `${count} install${count === 1 ? '' : 's'}`;
}
export interface SearchSkill {
name: string;
slug: string;
source: string;
installs: number;
}
// Search via API
export async function searchSkillsAPI(query: string): Promise<SearchSkill[]> {
try {
const url = `${SEARCH_API_BASE}/api/search?q=${encodeURIComponent(query)}&limit=10`;
const res = await fetch(url);
if (!res.ok) return [];
const data = (await res.json()) as {
skills: Array<{
id: string;
name: string;
installs: number;
source: string;
}>;
};
return data.skills
.map((skill) => ({
name: skill.name,
slug: skill.id,
source: skill.source || '',
installs: skill.installs,
}))
.sort((a, b) => (b.installs || 0) - (a.installs || 0));
} catch {
return [];
}
}
// ANSI escape codes for terminal control
const HIDE_CURSOR = '\x1b[?25l';
const SHOW_CURSOR = '\x1b[?25h';
const CLEAR_DOWN = '\x1b[J';
const MOVE_UP = (n: number) => `\x1b[${n}A`;
const MOVE_TO_COL = (n: number) => `\x1b[${n}G`;
// Custom fzf-style search prompt using raw readline
async function runSearchPrompt(initialQuery = ''): Promise<SearchSkill | null> {
let results: SearchSkill[] = [];
let selectedIndex = 0;
let query = initialQuery;
let loading = false;
let debounceTimer: ReturnType<typeof setTimeout> | null = null;
let lastRenderedLines = 0;
// Enable raw mode for keypress events
if (process.stdin.isTTY) {
process.stdin.setRawMode(true);
}
// Setup readline for keypress events but don't let it echo
readline.emitKeypressEvents(process.stdin);
// Resume stdin to start receiving events
process.stdin.resume();
// Hide cursor during selection
process.stdout.write(HIDE_CURSOR);
function render(): void {
// Move cursor up to overwrite previous render
if (lastRenderedLines > 0) {
process.stdout.write(MOVE_UP(lastRenderedLines) + MOVE_TO_COL(1));
}
// Clear from cursor to end of screen (removes ghost trails)
process.stdout.write(CLEAR_DOWN);
const lines: string[] = [];
// Search input line with cursor
const cursor = `${BOLD}_${RESET}`;
lines.push(`${TEXT}Search skills:${RESET} ${query}${cursor}`);
lines.push('');
// Results - keep showing existing results while loading new ones
if (!query || query.length < 2) {
lines.push(`${DIM}Start typing to search (min 2 chars)${RESET}`);
} else if (results.length === 0 && loading) {
lines.push(`${DIM}Searching...${RESET}`);
} else if (results.length === 0) {
lines.push(`${DIM}No skills found${RESET}`);
} else {
const maxVisible = 8;
const visible = results.slice(0, maxVisible);
for (let i = 0; i < visible.length; i++) {
const skill = visible[i]!;
const isSelected = i === selectedIndex;
const arrow = isSelected ? `${BOLD}>${RESET}` : ' ';
const name = isSelected ? `${BOLD}${skill.name}${RESET}` : `${TEXT}${skill.name}${RESET}`;
const source = skill.source ? ` ${DIM}${skill.source}${RESET}` : '';
const installs = formatInstalls(skill.installs);
const installsBadge = installs ? ` ${CYAN}${installs}${RESET}` : '';
const loadingIndicator = loading && i === 0 ? ` ${DIM}...${RESET}` : '';
lines.push(` ${arrow} ${name}${source}${installsBadge}${loadingIndicator}`);
}
}
lines.push('');
lines.push(`${DIM}up/down navigate | enter select | esc cancel${RESET}`);
// Write each line
for (const line of lines) {
process.stdout.write(line + '\n');
}
lastRenderedLines = lines.length;
}
function triggerSearch(q: string): void {
// Always clear any pending debounce timer
if (debounceTimer) {
clearTimeout(debounceTimer);
debounceTimer = null;
}
// Always reset loading state when starting a new search
loading = false;
if (!q || q.length < 2) {
results = [];
selectedIndex = 0;
render();
return;
}
// Use API search for all queries (debounced)
loading = true;
render();
// Adaptive debounce: shorter queries = longer wait (user still typing)
// 2 chars: 250ms, 3 chars: 200ms, 4 chars: 150ms, 5+ chars: 150ms
const debounceMs = Math.max(150, 350 - q.length * 50);
debounceTimer = setTimeout(async () => {
try {
results = await searchSkillsAPI(q);
selectedIndex = 0;
} catch {
results = [];
} finally {
loading = false;
debounceTimer = null;
render();
}
}, debounceMs);
}
// Trigger initial search if there's a query, then render
if (initialQuery) {
triggerSearch(initialQuery);
}
render();
return new Promise((resolve) => {
function cleanup(): void {
process.stdin.removeListener('keypress', handleKeypress);
if (process.stdin.isTTY) {
process.stdin.setRawMode(false);
}
process.stdout.write(SHOW_CURSOR);
// Pause stdin to fully release it for child processes
process.stdin.pause();
}
function handleKeypress(_ch: string | undefined, key: readline.Key): void {
if (!key) return;
if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
// Cancel
cleanup();
resolve(null);
return;
}
if (key.name === 'return') {
// Submit
cleanup();
resolve(results[selectedIndex] || null);
return;
}
if (key.name === 'up') {
selectedIndex = Math.max(0, selectedIndex - 1);
render();
return;
}
if (key.name === 'down') {
selectedIndex = Math.min(Math.max(0, results.length - 1), selectedIndex + 1);
render();
return;
}
if (key.name === 'backspace') {
if (query.length > 0) {
query = query.slice(0, -1);
triggerSearch(query);
}
return;
}
// Regular character input
if (key.sequence && !key.ctrl && !key.meta && key.sequence.length === 1) {
const char = key.sequence;
if (char >= ' ' && char <= '~') {
query += char;
triggerSearch(query);
}
}
}
process.stdin.on('keypress', handleKeypress);
});
}
// Parse owner/repo from a package string (for the find command)
function getOwnerRepoFromString(pkg: string): { owner: string; repo: string } | null {
// Handle owner/repo or owner/repo@skill
const atIndex = pkg.lastIndexOf('@');
const repoPath = atIndex > 0 ? pkg.slice(0, atIndex) : pkg;
const match = repoPath.match(/^([^/]+)\/([^/]+)$/);
if (match) {
return { owner: match[1]!, repo: match[2]! };
}
return null;
}
async function isRepoPublic(owner: string, repo: string): Promise<boolean> {
const isPrivate = await isRepoPrivate(owner, repo);
// Return true only if we know it's public (isPrivate === false)
// Return false if private or unable to determine
return isPrivate === false;
}
export async function runFind(args: string[]): Promise<void> {
const query = args.join(' ');
const isNonInteractive = !process.stdin.isTTY;
const agentTip = `${DIM}Tip: if running in a coding agent, follow these steps:${RESET}
${DIM} 1) npx skills find [query]${RESET}
${DIM} 2) npx skills add <owner/repo@skill>${RESET}`;
// Non-interactive mode: just print results and exit
if (query) {
const results = await searchSkillsAPI(query);
// Track telemetry for non-interactive search
track({
event: 'find',
query,
resultCount: String(results.length),
});
if (results.length === 0) {
console.log(`${DIM}No skills found for "${query}"${RESET}`);
return;
}
console.log(`${DIM}Install with${RESET} npx skills add <owner/repo@skill>`);
console.log();
for (const skill of results.slice(0, 6)) {
const pkg = skill.source || skill.slug;
const installs = formatInstalls(skill.installs);
console.log(
`${TEXT}${pkg}@${skill.name}${RESET}${installs ? ` ${CYAN}${installs}${RESET}` : ''}`
);
console.log(`${DIM}└ https://skills.sh/${skill.slug}${RESET}`);
console.log();
}
return;
}
// Interactive mode - show tip only if running non-interactively (likely in a coding agent)
if (isNonInteractive) {
console.log(agentTip);
console.log();
}
const selected = await runSearchPrompt();
// Track telemetry for interactive search
track({
event: 'find',
query: '',
resultCount: selected ? '1' : '0',
interactive: '1',
});
if (!selected) {
console.log(`${DIM}Search cancelled${RESET}`);
console.log();
return;
}
// Use source (owner/repo) and skill name for installation
const pkg = selected.source || selected.slug;
const skillName = selected.name;
console.log();
console.log(`${TEXT}Installing ${BOLD}${skillName}${RESET} from ${DIM}${pkg}${RESET}...`);
console.log();
// Run add directly since we're in the same CLI
const { source, options } = parseAddOptions([pkg, '--skill', skillName]);
await runAdd(source, options);
console.log();
const info = getOwnerRepoFromString(pkg);
if (info && (await isRepoPublic(info.owner, info.repo))) {
console.log(
`${DIM}View the skill at${RESET} ${TEXT}https://skills.sh/${selected.slug}${RESET}`
);
} else {
console.log(`
gitextract_8sxvogv3/ ├── .github/ │ ├── ISSUE_TEMPLATE/ │ │ ├── agent-request.yml │ │ ├── bug-report.yml │ │ ├── config.yml │ │ └── feature-request.yml │ ├── RELEASE_TEMPLATE.md │ └── workflows/ │ ├── agents.yml │ ├── ci.yml │ └── publish.yml ├── .gitignore ├── .husky/ │ └── pre-commit ├── .prettierrc ├── AGENTS.md ├── README.md ├── ThirdPartyNoticeText.txt ├── bin/ │ └── cli.mjs ├── build.config.mjs ├── package.json ├── scripts/ │ ├── execute-tests.ts │ ├── generate-licenses.ts │ ├── sync-agents.ts │ └── validate-agents.ts ├── skills/ │ └── find-skills/ │ └── SKILL.md ├── src/ │ ├── add-prompt.test.ts │ ├── add.test.ts │ ├── add.ts │ ├── agents.ts │ ├── cli.test.ts │ ├── cli.ts │ ├── constants.ts │ ├── find.ts │ ├── git.ts │ ├── init.test.ts │ ├── install.ts │ ├── installer.ts │ ├── list.test.ts │ ├── list.ts │ ├── local-lock.ts │ ├── plugin-manifest.ts │ ├── prompts/ │ │ └── search-multiselect.ts │ ├── providers/ │ │ ├── index.ts │ │ ├── registry.ts │ │ ├── types.ts │ │ └── wellknown.ts │ ├── remove.test.ts │ ├── remove.ts │ ├── skill-lock.ts │ ├── skills.ts │ ├── source-parser.test.ts │ ├── source-parser.ts │ ├── sync.ts │ ├── telemetry.ts │ ├── test-utils.ts │ └── types.ts ├── tests/ │ ├── cross-platform-paths.test.ts │ ├── dist.test.ts │ ├── full-depth-discovery.test.ts │ ├── installer-symlink.test.ts │ ├── list-installed.test.ts │ ├── local-lock.test.ts │ ├── openclaw-paths.test.ts │ ├── plugin-grouping.test.ts │ ├── plugin-manifest-discovery.test.ts │ ├── remove-canonical.test.ts │ ├── sanitize-name.test.ts │ ├── skill-matching.test.ts │ ├── skill-path.test.ts │ ├── source-parser.test.ts │ ├── subpath-traversal.test.ts │ ├── sync.test.ts │ ├── wellknown-provider.test.ts │ └── xdg-config-paths.test.ts └── tsconfig.json
SYMBOL INDEX (280 symbols across 35 files)
FILE: scripts/execute-tests.ts
type RunOptions (line 9) | type RunOptions = {
function parseArgs (line 16) | function parseArgs(argv: string[], rootDir: string): RunOptions {
function findTestFiles (line 46) | async function findTestFiles(dir: string): Promise<string[]> {
function runOneTest (line 64) | async function runOneTest(rootDir: string, testFile: string): Promise<nu...
function main (line 76) | async function main(): Promise<void> {
FILE: scripts/generate-licenses.ts
constant BUNDLED_PACKAGES (line 12) | const BUNDLED_PACKAGES = [
type LicenseInfo (line 23) | interface LicenseInfo {
function getLicenseText (line 30) | function getLicenseText(pkgPath: string): string {
function main (line 41) | function main() {
FILE: scripts/sync-agents.ts
constant ROOT (line 8) | const ROOT = join(import.meta.dirname, '..');
constant README_PATH (line 9) | const README_PATH = join(ROOT, 'README.md');
constant PACKAGE_PATH (line 10) | const PACKAGE_PATH = join(ROOT, 'package.json');
function generateAgentList (line 12) | function generateAgentList(): string {
function generateAgentNames (line 18) | function generateAgentNames(): string {
function generateAvailableAgentsTable (line 22) | function generateAvailableAgentsTable(): string {
function generateSkillDiscoveryPaths (line 64) | function generateSkillDiscoveryPaths(): string {
function generateKeywords (line 80) | function generateKeywords(): string[] {
function replaceSection (line 86) | function replaceSection(
function main (line 99) | function main() {
FILE: scripts/validate-agents.ts
function error (line 8) | function error(message: string) {
function checkDuplicateDisplayNames (line 23) | function checkDuplicateDisplayNames() {
function checkDuplicateSkillsDirs (line 55) | function checkDuplicateSkillsDirs() {
FILE: src/add.ts
function isSourcePrivate (line 16) | async function isSourcePrivate(source: string): Promise<boolean | null> {
function initTelemetry (line 60) | function initTelemetry(version: string): void {
function riskLabel (line 66) | function riskLabel(risk: string): string {
function socketLabel (line 83) | function socketLabel(audit: PartnerAudit | undefined): string {
function padEnd (line 90) | function padEnd(str: string, width: number): string {
function buildSecurityLines (line 101) | function buildSecurityLines(
function shortenPath (line 153) | function shortenPath(fullPath: string, cwd: string): string {
function formatList (line 168) | function formatList(items: string[], maxShow: number = 5): string {
function splitAgentsByType (line 181) | function splitAgentsByType(agentTypes: AgentType[]): {
function buildAgentSummaryLines (line 202) | function buildAgentSummaryLines(targetAgents: AgentType[], installMode: ...
function ensureUniversalAgents (line 226) | function ensureUniversalAgents(targetAgents: AgentType[]): AgentType[] {
function buildResultLines (line 242) | function buildResultLines(
function multiselect (line 277) | function multiselect<Value>(opts: {
function promptForAgents (line 296) | async function promptForAgents(
function selectAgentsInteractive (line 349) | async function selectAgentsInteractive(options: {
type AddOptions (line 410) | interface AddOptions {
function handleWellKnownSkills (line 425) | async function handleWellKnownSkills(
function runAdd (line 884) | async function runAdd(args: string[], options: AddOptions = {}): Promise...
function cleanup (line 1677) | async function cleanup(tempDir: string | null) {
function promptForFindSkills (line 1690) | async function promptForFindSkills(
function parseAddOptions (line 1763) | function parseAddOptions(args: string[]): { source: string[]; options: A...
FILE: src/agents.ts
function getOpenClawGlobalSkillsDir (line 13) | function getOpenClawGlobalSkillsDir(
function detectInstalledAgents (line 423) | async function detectInstalledAgents(): Promise<AgentType[]> {
function getAgentConfig (line 433) | function getAgentConfig(type: AgentType): AgentConfig {
function getUniversalAgents (line 442) | function getUniversalAgents(): AgentType[] {
function getNonUniversalAgents (line 454) | function getNonUniversalAgents(): AgentType[] {
function isUniversalAgent (line 463) | function isUniversalAgent(type: AgentType): boolean {
FILE: src/cli.ts
function getVersion (line 19) | function getVersion(): string {
constant VERSION (line 29) | const VERSION = getVersion();
constant RESET (line 32) | const RESET = '\x1b[0m';
constant BOLD (line 33) | const BOLD = '\x1b[1m';
constant DIM (line 35) | const DIM = '\x1b[38;5;102m';
constant TEXT (line 36) | const TEXT = '\x1b[38;5;145m';
constant LOGO_LINES (line 38) | const LOGO_LINES = [
constant GRAYS (line 48) | const GRAYS = [
function showLogo (line 57) | function showLogo(): void {
function showBanner (line 64) | function showBanner(): void {
function showHelp (line 105) | function showHelp(): void {
function showRemoveHelp (line 181) | function showRemoveHelp(): void {
function runInit (line 212) | function runInit(args: string[]): void {
constant AGENTS_DIR (line 279) | const AGENTS_DIR = '.agents';
constant LOCK_FILE (line 280) | const LOCK_FILE = '.skill-lock.json';
constant CURRENT_LOCK_VERSION (line 281) | const CURRENT_LOCK_VERSION = 3;
type SkillLockEntry (line 283) | interface SkillLockEntry {
type SkillLockFile (line 294) | interface SkillLockFile {
function getSkillLockPath (line 299) | function getSkillLockPath(): string {
function readSkillLock (line 307) | function readSkillLock(): SkillLockFile {
type SkippedSkill (line 326) | interface SkippedSkill {
function getSkipReason (line 335) | function getSkipReason(entry: SkillLockEntry): string {
function printSkippedSkills (line 355) | function printSkippedSkills(skipped: SkippedSkill[]): void {
function runCheck (line 365) | async function runCheck(args: string[] = []): Promise<void> {
function runUpdate (line 475) | async function runUpdate(): Promise<void> {
function main (line 608) | async function main(): Promise<void> {
FILE: src/constants.ts
constant AGENTS_DIR (line 1) | const AGENTS_DIR = '.agents';
constant SKILLS_SUBDIR (line 2) | const SKILLS_SUBDIR = 'skills';
constant UNIVERSAL_SKILLS_DIR (line 3) | const UNIVERSAL_SKILLS_DIR = '.agents/skills';
FILE: src/find.ts
constant RESET (line 6) | const RESET = '\x1b[0m';
constant BOLD (line 7) | const BOLD = '\x1b[1m';
constant DIM (line 8) | const DIM = '\x1b[38;5;102m';
constant TEXT (line 9) | const TEXT = '\x1b[38;5;145m';
constant CYAN (line 10) | const CYAN = '\x1b[36m';
constant MAGENTA (line 11) | const MAGENTA = '\x1b[35m';
constant YELLOW (line 12) | const YELLOW = '\x1b[33m';
constant SEARCH_API_BASE (line 15) | const SEARCH_API_BASE = process.env.SKILLS_API_URL || 'https://skills.sh';
function formatInstalls (line 17) | function formatInstalls(count: number): string {
type SearchSkill (line 24) | interface SearchSkill {
function searchSkillsAPI (line 32) | async function searchSkillsAPI(query: string): Promise<SearchSkill[]> {
constant HIDE_CURSOR (line 62) | const HIDE_CURSOR = '\x1b[?25l';
constant SHOW_CURSOR (line 63) | const SHOW_CURSOR = '\x1b[?25h';
constant CLEAR_DOWN (line 64) | const CLEAR_DOWN = '\x1b[J';
function runSearchPrompt (line 69) | async function runSearchPrompt(initialQuery = ''): Promise<SearchSkill |...
function getOwnerRepoFromString (line 251) | function getOwnerRepoFromString(pkg: string): { owner: string; repo: str...
function isRepoPublic (line 262) | async function isRepoPublic(owner: string, repo: string): Promise<boolea...
function runFind (line 269) | async function runFind(args: string[]): Promise<void> {
FILE: src/git.ts
constant CLONE_TIMEOUT_MS (line 6) | const CLONE_TIMEOUT_MS = 60000;
class GitCloneError (line 8) | class GitCloneError extends Error {
method constructor (line 13) | constructor(message: string, url: string, isTimeout = false, isAuthErr...
function cloneRepo (line 22) | async function cloneRepo(url: string, ref?: string): Promise<string> {
function cleanupTempDir (line 73) | async function cleanupTempDir(dir: string): Promise<void> {
FILE: src/install.ts
function runInstallFromLock (line 17) | async function runInstallFromLock(args: string[]): Promise<void> {
FILE: src/installer.ts
type InstallMode (line 23) | type InstallMode = 'symlink' | 'copy';
type InstallResult (line 25) | interface InstallResult {
function sanitizeName (line 40) | function sanitizeName(name: string): string {
function isPathSafe (line 63) | function isPathSafe(basePath: string, targetPath: string): boolean {
function getCanonicalSkillsDir (line 70) | function getCanonicalSkillsDir(global: boolean, cwd?: string): string {
function getAgentBaseDir (line 80) | function getAgentBaseDir(agentType: AgentType, global: boolean, cwd?: st...
function resolveSymlinkTarget (line 99) | function resolveSymlinkTarget(linkPath: string, linkTarget: string): str...
function cleanAndCreateDirectory (line 111) | async function cleanAndCreateDirectory(path: string): Promise<void> {
function resolveParentSymlinks (line 129) | async function resolveParentSymlinks(path: string): Promise<string> {
function createSymlink (line 145) | async function createSymlink(target: string, linkPath: string): Promise<...
function installSkillForAgent (line 212) | async function installSkillForAgent(
constant EXCLUDE_FILES (line 325) | const EXCLUDE_FILES = new Set(['metadata.json']);
constant EXCLUDE_DIRS (line 326) | const EXCLUDE_DIRS = new Set(['.git', '__pycache__', '__pypackages__']);
function copyDirectory (line 335) | async function copyDirectory(src: string, dest: string): Promise<void> {
function isSkillInstalled (line 379) | async function isSkillInstalled(
function getInstallPath (line 410) | function getInstallPath(
function getCanonicalPath (line 432) | function getCanonicalPath(
function installRemoteSkillForAgent (line 453) | async function installRemoteSkillForAgent(
function installWellKnownSkillForAgent (line 572) | async function installWellKnownSkillForAgent(
type InstalledSkill (line 702) | interface InstalledSkill {
function listInstalledSkills (line 716) | async function listInstalledSkills(
FILE: src/list.ts
constant RESET (line 7) | const RESET = '\x1b[0m';
constant BOLD (line 8) | const BOLD = '\x1b[1m';
constant DIM (line 9) | const DIM = '\x1b[38;5;102m';
constant TEXT (line 10) | const TEXT = '\x1b[38;5;145m';
constant CYAN (line 11) | const CYAN = '\x1b[36m';
constant YELLOW (line 12) | const YELLOW = '\x1b[33m';
type ListOptions (line 14) | interface ListOptions {
function shortenPath (line 23) | function shortenPath(fullPath: string, cwd: string): string {
function formatList (line 37) | function formatList(items: string[], maxShow: number = 5): string {
function parseListOptions (line 46) | function parseListOptions(args: string[]): ListOptions {
function runList (line 67) | async function runList(args: string[]): Promise<void> {
FILE: src/local-lock.ts
constant LOCAL_LOCK_FILE (line 5) | const LOCAL_LOCK_FILE = 'skills-lock.json';
constant CURRENT_VERSION (line 6) | const CURRENT_VERSION = 1;
type LocalSkillLockEntry (line 15) | interface LocalSkillLockEntry {
type LocalSkillLockFile (line 35) | interface LocalSkillLockFile {
function getLocalLockPath (line 45) | function getLocalLockPath(cwd?: string): string {
function readLocalLock (line 54) | async function readLocalLock(cwd?: string): Promise<LocalSkillLockFile> {
function writeLocalLock (line 79) | async function writeLocalLock(lock: LocalSkillLockFile, cwd?: string): P...
function computeSkillFolderHash (line 98) | async function computeSkillFolderHash(skillDir: string): Promise<string> {
function collectFiles (line 115) | async function collectFiles(
function addSkillToLocalLock (line 142) | async function addSkillToLocalLock(
function removeSkillFromLocalLock (line 155) | async function removeSkillFromLocalLock(skillName: string, cwd?: string)...
function createEmptyLocalLock (line 167) | function createEmptyLocalLock(): LocalSkillLockFile {
FILE: src/plugin-manifest.ts
function isContainedIn (line 8) | function isContainedIn(targetPath: string, basePath: string): boolean {
function isValidRelativePath (line 18) | function isValidRelativePath(path: string): boolean {
type PluginManifestEntry (line 25) | interface PluginManifestEntry {
type MarketplaceManifest (line 32) | interface MarketplaceManifest {
type PluginManifest (line 37) | interface PluginManifest {
function getPluginSkillPaths (line 51) | async function getPluginSkillPaths(basePath: string): Promise<string[]> {
function getPluginGroupings (line 120) | async function getPluginGroupings(basePath: string): Promise<Map<string,...
FILE: src/prompts/search-multiselect.ts
method write (line 7) | write(_chunk, _encoding, callback) {
type SearchItem (line 12) | interface SearchItem<T> {
type LockedSection (line 18) | interface LockedSection<T> {
type SearchMultiselectOptions (line 23) | interface SearchMultiselectOptions<T> {
constant S_STEP_ACTIVE (line 34) | const S_STEP_ACTIVE = pc.green('◆');
constant S_STEP_CANCEL (line 35) | const S_STEP_CANCEL = pc.red('■');
constant S_STEP_SUBMIT (line 36) | const S_STEP_SUBMIT = pc.green('◇');
constant S_RADIO_ACTIVE (line 37) | const S_RADIO_ACTIVE = pc.green('●');
constant S_RADIO_INACTIVE (line 38) | const S_RADIO_INACTIVE = pc.dim('○');
constant S_CHECKBOX_LOCKED (line 39) | const S_CHECKBOX_LOCKED = pc.green('✓');
constant S_BULLET (line 40) | const S_BULLET = pc.green('•');
constant S_BAR (line 41) | const S_BAR = pc.dim('│');
constant S_BAR_H (line 42) | const S_BAR_H = pc.dim('─');
function searchMultiselect (line 51) | async function searchMultiselect<T>(
FILE: src/providers/registry.ts
class ProviderRegistryImpl (line 3) | class ProviderRegistryImpl implements ProviderRegistry {
method register (line 6) | register(provider: HostProvider): void {
method findProvider (line 14) | findProvider(url: string): HostProvider | null {
method getProviders (line 24) | getProviders(): HostProvider[] {
function registerProvider (line 35) | function registerProvider(provider: HostProvider): void {
function findProvider (line 42) | function findProvider(url: string): HostProvider | null {
function getProviders (line 49) | function getProviders(): HostProvider[] {
FILE: src/providers/types.ts
type RemoteSkill (line 5) | interface RemoteSkill {
type ProviderMatch (line 23) | interface ProviderMatch {
type HostProvider (line 38) | interface HostProvider {
type ProviderRegistry (line 80) | interface ProviderRegistry {
FILE: src/providers/wellknown.ts
type WellKnownIndex (line 7) | interface WellKnownIndex {
type WellKnownSkillEntry (line 14) | interface WellKnownSkillEntry {
type WellKnownSkill (line 26) | interface WellKnownSkill extends RemoteSkill {
class WellKnownProvider (line 47) | class WellKnownProvider implements HostProvider {
method match (line 59) | match(url: string): ProviderMatch {
method fetchIndex (line 88) | async fetchIndex(
method isValidSkillEntry (line 155) | private isValidSkillEntry(entry: unknown): entry is WellKnownSkillEntry {
method fetchSkill (line 191) | async fetchSkill(url: string): Promise<RemoteSkill | null> {
method fetchSkillByEntry (line 237) | async fetchSkillByEntry(
method fetchAllSkills (line 306) | async fetchAllSkills(url: string): Promise<WellKnownSkill[]> {
method toRawUrl (line 331) | toRawUrl(url: string): string {
method getSourceIdentifier (line 362) | getSourceIdentifier(url: string): string {
method hasSkillsIndex (line 375) | async hasSkillsIndex(url: string): Promise<boolean> {
FILE: src/remove.test.ts
function createTestSkill (line 26) | function createTestSkill(name: string, description?: string) {
function createAgentSkillsDir (line 43) | function createAgentSkillsDir(agentName: string) {
function createSymlink (line 49) | function createSymlink(skillName: string, targetDir: string) {
FILE: src/remove.ts
type RemoveOptions (line 16) | interface RemoveOptions {
function removeCommand (line 23) | async function removeCommand(skillNames: string[], options: RemoveOption...
function parseRemoveOptions (line 282) | function parseRemoveOptions(args: string[]): { skills: string[]; options...
FILE: src/skill-lock.ts
constant AGENTS_DIR (line 7) | const AGENTS_DIR = '.agents';
constant LOCK_FILE (line 8) | const LOCK_FILE = '.skill-lock.json';
constant CURRENT_VERSION (line 9) | const CURRENT_VERSION = 3;
type SkillLockEntry (line 14) | interface SkillLockEntry {
type DismissedPrompts (line 40) | interface DismissedPrompts {
type SkillLockFile (line 48) | interface SkillLockFile {
function getSkillLockPath (line 64) | function getSkillLockPath(): string {
function readSkillLock (line 77) | async function readSkillLock(): Promise<SkillLockFile> {
function writeSkillLock (line 106) | async function writeSkillLock(lock: SkillLockFile): Promise<void> {
function computeContentHash (line 120) | function computeContentHash(content: string): string {
function getGitHubToken (line 133) | function getGitHubToken(): string | null {
function fetchSkillFolderHash (line 168) | async function fetchSkillFolderHash(
function addSkillToLock (line 234) | async function addSkillToLock(
function removeSkillFromLock (line 255) | async function removeSkillFromLock(skillName: string): Promise<boolean> {
function getSkillFromLock (line 270) | async function getSkillFromLock(skillName: string): Promise<SkillLockEnt...
function getAllLockedSkills (line 278) | async function getAllLockedSkills(): Promise<Record<string, SkillLockEnt...
function getSkillsBySource (line 286) | async function getSkillsBySource(): Promise<
function createEmptyLockFile (line 307) | function createEmptyLockFile(): SkillLockFile {
function isPromptDismissed (line 318) | async function isPromptDismissed(promptKey: keyof DismissedPrompts): Pro...
function dismissPrompt (line 326) | async function dismissPrompt(promptKey: keyof DismissedPrompts): Promise...
function getLastSelectedAgents (line 338) | async function getLastSelectedAgents(): Promise<string[] | undefined> {
function saveSelectedAgents (line 346) | async function saveSelectedAgents(agents: string[]): Promise<void> {
FILE: src/skills.ts
constant SKIP_DIRS (line 7) | const SKIP_DIRS = ['node_modules', '.git', 'dist', 'build', '__pycache__'];
function shouldInstallInternalSkills (line 13) | function shouldInstallInternalSkills(): boolean {
function hasSkillMd (line 18) | async function hasSkillMd(dir: string): Promise<boolean> {
function parseSkillMd (line 28) | async function parseSkillMd(
function findSkillDirs (line 65) | async function findSkillDirs(dir: string, depth = 0, maxDepth = 5): Prom...
type DiscoverSkillsOptions (line 89) | interface DiscoverSkillsOptions {
function isSubpathSafe (line 101) | function isSubpathSafe(basePath: string, subpath: string): boolean {
function discoverSkills (line 108) | async function discoverSkills(
function getSkillDisplayName (line 227) | function getSkillDisplayName(skill: Skill): string {
function filterSkills (line 235) | function filterSkills(skills: Skill[], inputNames: string[]): Skill[] {
FILE: src/source-parser.ts
function getOwnerRepo (line 10) | function getOwnerRepo(parsed: ParsedSource): string | null {
function parseOwnerRepo (line 54) | function parseOwnerRepo(ownerRepo: string): { owner: string; repo: strin...
function isRepoPrivate (line 67) | async function isRepoPrivate(owner: string, repo: string): Promise<boole...
function sanitizeSubpath (line 89) | function sanitizeSubpath(subpath: string): string {
function isLocalPath (line 110) | function isLocalPath(input: string): boolean {
constant SOURCE_ALIASES (line 127) | const SOURCE_ALIASES: Record<string, string> = {
function parseSource (line 131) | function parseSource(input: string): ParsedSource {
function isWellKnownUrl (line 286) | function isWellKnownUrl(input: string): boolean {
FILE: src/sync.ts
type SyncOptions (line 21) | interface SyncOptions {
function shortenPath (line 30) | function shortenPath(fullPath: string, cwd: string): string {
function discoverNodeModuleSkills (line 46) | async function discoverNodeModuleSkills(
function runSync (line 132) | async function runSync(args: string[], options: SyncOptions = {}): Promi...
function parseSyncOptions (line 423) | function parseSyncOptions(args: string[]): { options: SyncOptions } {
FILE: src/telemetry.ts
constant TELEMETRY_URL (line 1) | const TELEMETRY_URL = 'https://add-skill.vercel.sh/t';
constant AUDIT_URL (line 2) | const AUDIT_URL = 'https://add-skill.vercel.sh/audit';
type InstallTelemetryData (line 4) | interface InstallTelemetryData {
type RemoveTelemetryData (line 20) | interface RemoveTelemetryData {
type CheckTelemetryData (line 29) | interface CheckTelemetryData {
type UpdateTelemetryData (line 35) | interface UpdateTelemetryData {
type FindTelemetryData (line 42) | interface FindTelemetryData {
type SyncTelemetryData (line 49) | interface SyncTelemetryData {
type TelemetryData (line 56) | type TelemetryData =
function isCI (line 66) | function isCI(): boolean {
function isEnabled (line 79) | function isEnabled(): boolean {
function setVersion (line 83) | function setVersion(version: string): void {
type PartnerAudit (line 89) | interface PartnerAudit {
type SkillAuditData (line 96) | type SkillAuditData = Record<string, PartnerAudit>;
type AuditResponse (line 97) | type AuditResponse = Record<string, SkillAuditData>;
function fetchAuditData (line 103) | async function fetchAuditData(
function track (line 131) | function track(data: TelemetryData): void {
FILE: src/test-utils.ts
constant CLI_PATH (line 5) | const CLI_PATH = join(import.meta.dirname, 'cli.ts');
function stripAnsi (line 7) | function stripAnsi(str: string): string {
function stripLogo (line 11) | function stripLogo(str: string): string {
function hasLogo (line 19) | function hasLogo(str: string): boolean {
function runCli (line 23) | function runCli(
function runCliOutput (line 47) | function runCliOutput(args: string[], cwd?: string): string {
function runCliWithInput (line 52) | function runCliWithInput(
FILE: src/types.ts
type AgentType (line 1) | type AgentType =
type Skill (line 46) | interface Skill {
type AgentConfig (line 57) | interface AgentConfig {
type ParsedSource (line 68) | interface ParsedSource {
type RemoteSkill (line 81) | interface RemoteSkill {
FILE: tests/cross-platform-paths.test.ts
function shortenPath (line 14) | function shortenPath(fullPath: string, cwd: string, home: string, pathSe...
function isValidSkillFile (line 30) | function isValidSkillFile(file: string): boolean {
function normalizeSkillPath (line 40) | function normalizeSkillPath(skillPath: string): string {
FILE: tests/installer-symlink.test.ts
function makeSkillSource (line 21) | async function makeSkillSource(root: string, name: string): Promise<stri...
FILE: tests/list-installed.test.ts
function createSkillDir (line 21) | async function createSkillDir(
FILE: tests/plugin-grouping.test.ts
constant TEST_DIR (line 6) | const TEST_DIR = join(process.cwd(), 'test-plugin-grouping');
FILE: tests/skill-matching.test.ts
function makeSkill (line 16) | function makeSkill(name: string, path: string = '/tmp/skill'): Skill {
FILE: tests/skill-path.test.ts
function calculateRelativePath (line 15) | function calculateRelativePath(
FILE: tests/xdg-config-paths.test.ts
function getSkillLockPath (line 64) | function getSkillLockPath(xdgStateHome: string | undefined, homeDir: str...
Condensed preview — 72 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (503K chars).
[
{
"path": ".github/ISSUE_TEMPLATE/agent-request.yml",
"chars": 1414,
"preview": "name: Agent Request\ndescription: Request support for a new coding agent\ntitle: \"[Agent]: \"\nlabels: [\"enhancement\"]\nbody:"
},
{
"path": ".github/ISSUE_TEMPLATE/bug-report.yml",
"chars": 1839,
"preview": "name: Bug Report\ndescription: Report a bug or issue\ntitle: \"[Bug]: \"\nlabels: [\"bug\"]\nbody:\n - type: markdown\n attrib"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"chars": 302,
"preview": "blank_issues_enabled: true\ncontact_links:\n - name: Documentation\n url: https://github.com/vercel-labs/add-skill#read"
},
{
"path": ".github/ISSUE_TEMPLATE/feature-request.yml",
"chars": 1086,
"preview": "name: Feature Request\ndescription: Suggest a new feature or improvement\ntitle: \"[Feature]: \"\nlabels: [\"enhancement\"]\nbod"
},
{
"path": ".github/RELEASE_TEMPLATE.md",
"chars": 61,
"preview": "## Changelog\n\n${CHANGELOG}\n\n## Contributors\n\n${CONTRIBUTORS}\n"
},
{
"path": ".github/workflows/agents.yml",
"chars": 1724,
"preview": "name: Agents CI\n\non:\n pull_request:\n paths:\n - \"src/agents.ts\"\n push:\n branches: [main]\n paths:\n - "
},
{
"path": ".github/workflows/ci.yml",
"chars": 782,
"preview": "name: CI\n\non:\n pull_request:\n paths-ignore:\n - \"**/*.md\"\n push:\n branches: [main]\n paths-ignore:\n -"
},
{
"path": ".github/workflows/publish.yml",
"chars": 4995,
"preview": "name: Publish\n\non:\n push:\n branches: [main]\n tags:\n - 'v*'\n paths-ignore:\n - '**/*.md'\n workflow_di"
},
{
"path": ".gitignore",
"chars": 575,
"preview": "# dependencies (bun install)\nnode_modules\n\n# output\nout\ndist\n*.tgz\n\n# code coverage\ncoverage\n*.lcov\n\n# logs\nlogs\n_.log\nr"
},
{
"path": ".husky/pre-commit",
"chars": 17,
"preview": "pnpm lint-staged\n"
},
{
"path": ".prettierrc",
"chars": 106,
"preview": "{\n \"semi\": true,\n \"singleQuote\": true,\n \"trailingComma\": \"es5\",\n \"printWidth\": 100,\n \"tabWidth\": 2\n}\n"
},
{
"path": "AGENTS.md",
"chars": 6751,
"preview": "# AGENTS.md\n\nThis file provides guidance to AI coding agents working on the `skills` CLI codebase.\n\n## Project Overview\n"
},
{
"path": "README.md",
"chars": 18221,
"preview": "# skills\n\nThe CLI for the open agent skills ecosystem.\n\n<!-- agent-list:start -->\nSupports **OpenCode**, **Claude Code**"
},
{
"path": "ThirdPartyNoticeText.txt",
"chars": 9605,
"preview": "/*!----------------- Skills CLI ThirdPartyNotices -------------------------------------------------------\n\nThe Skills CL"
},
{
"path": "bin/cli.mjs",
"chars": 305,
"preview": "#!/usr/bin/env node\n\nimport module from 'node:module';\n\n// https://nodejs.org/api/module.html#module-compile-cache\nif (m"
},
{
"path": "build.config.mjs",
"chars": 181,
"preview": "import { defineBuildConfig } from 'obuild/config';\n\n// https://github.com/unjs/obuild\nexport default defineBuildConfig({"
},
{
"path": "package.json",
"chars": 2499,
"preview": "{\n \"name\": \"skills\",\n \"version\": \"1.4.5\",\n \"description\": \"The open agent skills ecosystem\",\n \"type\": \"module\",\n \"b"
},
{
"path": "scripts/execute-tests.ts",
"chars": 3174,
"preview": "#!/usr/bin/env node\n\nimport { spawn } from 'node:child_process';\nimport { readdir } from 'node:fs/promises';\nimport path"
},
{
"path": "scripts/generate-licenses.ts",
"chars": 5613,
"preview": "#!/usr/bin/env node\n/**\n * Generates ThirdPartyNoticeText.txt for bundled dependencies.\n * Run during build to ensure li"
},
{
"path": "scripts/sync-agents.ts",
"chars": 3656,
"preview": "#!/usr/bin/env node\n\nimport { readFileSync, writeFileSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } f"
},
{
"path": "scripts/validate-agents.ts",
"chars": 2880,
"preview": "#!/usr/bin/env node\n\nimport { homedir } from 'os';\nimport { agents } from '../src/agents.ts';\n\nlet hasErrors = false;\n\nf"
},
{
"path": "skills/find-skills/SKILL.md",
"chars": 5430,
"preview": "---\nname: find-skills\ndescription: Helps users discover and install agent skills when they ask questions like \"how do I "
},
{
"path": "src/add-prompt.test.ts",
"chars": 3718,
"preview": "import { describe, it, expect, vi, beforeEach } from 'vitest';\nimport { promptForAgents } from './add.js';\nimport * as s"
},
{
"path": "src/add.test.ts",
"chars": 13004,
"preview": "import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';\nimport { existsSync, rmSync, mkdirSync, writeF"
},
{
"path": "src/add.ts",
"chars": 58946,
"preview": "import * as p from '@clack/prompts';\nimport pc from 'picocolors';\nimport { existsSync } from 'fs';\nimport { homedir } fr"
},
{
"path": "src/agents.ts",
"chars": 13237,
"preview": "import { homedir } from 'os';\nimport { join } from 'path';\nimport { existsSync } from 'fs';\nimport { xdgConfig } from 'x"
},
{
"path": "src/cli.test.ts",
"chars": 3116,
"preview": "import { describe, it, expect } from 'vitest';\nimport { readFileSync } from 'fs';\nimport { join } from 'path';\nimport { "
},
{
"path": "src/cli.ts",
"chars": 22603,
"preview": "#!/usr/bin/env node\n\nimport { spawnSync } from 'child_process';\nimport { writeFileSync, readFileSync, existsSync, mkdirS"
},
{
"path": "src/constants.ts",
"chars": 130,
"preview": "export const AGENTS_DIR = '.agents';\nexport const SKILLS_SUBDIR = 'skills';\nexport const UNIVERSAL_SKILLS_DIR = '.agents"
},
{
"path": "src/find.ts",
"chars": 10302,
"preview": "import * as readline from 'readline';\nimport { runAdd, parseAddOptions } from './add.ts';\nimport { track } from './telem"
},
{
"path": "src/git.ts",
"chars": 2969,
"preview": "import simpleGit from 'simple-git';\nimport { join, normalize, resolve, sep } from 'path';\nimport { mkdtemp, rm } from 'f"
},
{
"path": "src/init.test.ts",
"chars": 3562,
"preview": "import { describe, it, expect, beforeEach, afterEach } from 'vitest';\nimport { existsSync, rmSync, readFileSync, mkdirSy"
},
{
"path": "src/install.ts",
"chars": 2929,
"preview": "import * as p from '@clack/prompts';\nimport pc from 'picocolors';\nimport { readLocalLock } from './local-lock.ts';\nimpor"
},
{
"path": "src/installer.ts",
"chars": 29864,
"preview": "import {\n mkdir,\n cp,\n access,\n readdir,\n symlink,\n lstat,\n rm,\n readlink,\n writeFile,\n stat,\n realpath,\n} fr"
},
{
"path": "src/list.test.ts",
"chars": 11590,
"preview": "import { describe, it, expect, beforeEach, afterEach } from 'vitest';\nimport { existsSync, rmSync, mkdirSync, writeFileS"
},
{
"path": "src/list.ts",
"chars": 5671,
"preview": "import { homedir } from 'os';\nimport type { AgentType } from './types.ts';\nimport { agents } from './agents.ts';\nimport "
},
{
"path": "src/local-lock.ts",
"chars": 5287,
"preview": "import { readFile, writeFile, readdir, stat } from 'fs/promises';\nimport { join, relative } from 'path';\nimport { create"
},
{
"path": "src/plugin-manifest.ts",
"chars": 6778,
"preview": "import { readFile } from 'fs/promises';\nimport { join, dirname, resolve, normalize, sep } from 'path';\n\n/**\n * Check if "
},
{
"path": "src/prompts/search-multiselect.ts",
"chars": 9231,
"preview": "import * as readline from 'readline';\nimport { Writable } from 'stream';\nimport pc from 'picocolors';\n\n// Silent writabl"
},
{
"path": "src/providers/index.ts",
"chars": 410,
"preview": "// Export types\nexport type { HostProvider, ProviderMatch, ProviderRegistry, RemoteSkill } from './types.ts';\n\n// Export"
},
{
"path": "src/providers/registry.ts",
"chars": 1251,
"preview": "import type { HostProvider, ProviderRegistry } from './types.ts';\n\nclass ProviderRegistryImpl implements ProviderRegistr"
},
{
"path": "src/providers/types.ts",
"chars": 2813,
"preview": "/**\n * Represents a parsed skill from a remote host.\n * Different hosts may have different ways of identifying skills.\n "
},
{
"path": "src/providers/wellknown.ts",
"chars": 11757,
"preview": "import matter from 'gray-matter';\nimport type { HostProvider, ProviderMatch, RemoteSkill } from './types.ts';\n\n/**\n * Re"
},
{
"path": "src/remove.test.ts",
"chars": 11365,
"preview": "import { describe, it, expect, beforeEach, afterEach } from 'vitest';\nimport { existsSync, rmSync, mkdirSync, writeFileS"
},
{
"path": "src/remove.ts",
"chars": 9415,
"preview": "import * as p from '@clack/prompts';\nimport pc from 'picocolors';\nimport { readdir, rm, lstat } from 'fs/promises';\nimpo"
},
{
"path": "src/skill-lock.ts",
"chars": 9705,
"preview": "import { readFile, writeFile, mkdir } from 'fs/promises';\nimport { join, dirname } from 'path';\nimport { homedir } from "
},
{
"path": "src/skills.ts",
"chars": 7920,
"preview": "import { readdir, readFile, stat } from 'fs/promises';\nimport { join, basename, dirname, resolve, normalize, sep } from "
},
{
"path": "src/source-parser.test.ts",
"chars": 3168,
"preview": "import { describe, it, expect } from 'vitest';\nimport { parseSource } from './source-parser.js';\n\ndescribe('source-parse"
},
{
"path": "src/source-parser.ts",
"chars": 9888,
"preview": "import { isAbsolute, resolve } from 'path';\nimport type { ParsedSource } from './types.ts';\n\n/**\n * Extract owner/repo ("
},
{
"path": "src/sync.ts",
"chars": 13352,
"preview": "import * as p from '@clack/prompts';\nimport pc from 'picocolors';\nimport { readdir, stat } from 'fs/promises';\nimport { "
},
{
"path": "src/telemetry.ts",
"chars": 3662,
"preview": "const TELEMETRY_URL = 'https://add-skill.vercel.sh/t';\nconst AUDIT_URL = 'https://add-skill.vercel.sh/audit';\n\ninterface"
},
{
"path": "src/test-utils.ts",
"chars": 2002,
"preview": "import { execSync } from 'child_process';\nimport { join } from 'path';\n\n// const PROJECT_ROOT = join(import.meta.dirname"
},
{
"path": "src/types.ts",
"chars": 2263,
"preview": "export type AgentType =\n | 'amp'\n | 'antigravity'\n | 'augment'\n | 'claude-code'\n | 'openclaw'\n | 'cline'\n | 'code"
},
{
"path": "tests/cross-platform-paths.test.ts",
"chars": 9667,
"preview": "/**\n * Cross-platform path handling tests.\n *\n * These tests verify that path operations work correctly on both Unix and"
},
{
"path": "tests/dist.test.ts",
"chars": 605,
"preview": "import { describe, it, expect } from 'vitest';\nimport { execSync } from 'node:child_process';\nimport { join } from 'node"
},
{
"path": "tests/full-depth-discovery.test.ts",
"chars": 4956,
"preview": "/**\n * Tests for the --full-depth option in skill discovery.\n *\n * When a repository has both a root SKILL.md and nested"
},
{
"path": "tests/installer-symlink.test.ts",
"chars": 7507,
"preview": "/**\n * Regression tests for symlink installs when canonical and agent paths match.\n */\n\nimport { describe, it, expect } "
},
{
"path": "tests/list-installed.test.ts",
"chars": 6330,
"preview": "import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';\nimport { mkdir, writeFile, rm } from 'fs/promi"
},
{
"path": "tests/local-lock.test.ts",
"chars": 13545,
"preview": "import { describe, it, expect } from 'vitest';\nimport { mkdtemp, mkdir, rm, writeFile, readFile } from 'node:fs/promises"
},
{
"path": "tests/openclaw-paths.test.ts",
"chars": 1217,
"preview": "import { join } from 'path';\nimport { describe, it, expect } from 'vitest';\nimport { getOpenClawGlobalSkillsDir } from '"
},
{
"path": "tests/plugin-grouping.test.ts",
"chars": 2316,
"preview": "import { join, resolve } from 'path';\nimport { getPluginGroupings } from '../src/plugin-manifest.ts';\nimport { describe,"
},
{
"path": "tests/plugin-manifest-discovery.test.ts",
"chars": 17456,
"preview": "/**\n * Tests for discovering skills declared in plugin manifests.\n */\nimport { describe, it, expect, beforeEach, afterEa"
},
{
"path": "tests/remove-canonical.test.ts",
"chars": 3949,
"preview": "import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';\nimport { mkdir, rm, writeFile, lstat, symlink "
},
{
"path": "tests/sanitize-name.test.ts",
"chars": 4713,
"preview": "/**\n * Unit tests for sanitizeName function in installer.ts\n *\n * These tests verify the sanitization logic for skill na"
},
{
"path": "tests/skill-matching.test.ts",
"chars": 5212,
"preview": "/**\n * Unit tests for filterSkills function in skills.ts\n *\n * These tests verify the skill matching logic. Multi-word s"
},
{
"path": "tests/skill-path.test.ts",
"chars": 5293,
"preview": "/**\n * Unit tests for skill path calculation in telemetry.\n *\n * These tests verify that the relativePath calculation fo"
},
{
"path": "tests/source-parser.test.ts",
"chars": 15727,
"preview": "/**\n * Unit tests for source-parser.ts\n *\n * These tests verify the URL parsing logic - they don't make network requests"
},
{
"path": "tests/subpath-traversal.test.ts",
"chars": 4449,
"preview": "/**\n * Tests for path traversal prevention in subpath handling.\n *\n * These tests verify that:\n * 1. parseSource() rejec"
},
{
"path": "tests/sync.test.ts",
"chars": 7585,
"preview": "import { describe, it, expect, beforeEach, afterEach } from 'vitest';\nimport { existsSync, mkdirSync, writeFileSync, rea"
},
{
"path": "tests/wellknown-provider.test.ts",
"chars": 5171,
"preview": "import { describe, it, expect } from 'vitest';\nimport { WellKnownProvider } from '../src/providers/wellknown.ts';\n\ndescr"
},
{
"path": "tests/xdg-config-paths.test.ts",
"chars": 3577,
"preview": "/**\n * Tests for XDG config path handling (cross-platform).\n *\n * These tests verify that agents using XDG Base Director"
},
{
"path": "tsconfig.json",
"chars": 774,
"preview": "{\n \"compilerOptions\": {\n // Environment setup & latest features\n \"lib\": [\"ESNext\"],\n \"target\": \"ESNext\",\n \""
}
]
About this extraction
This page contains the full source code of the vercel-labs/skills GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 72 files (471.8 KB), approximately 120.2k tokens, and a symbol index with 280 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.