Skip to main content
We welcome contributions to the Skills CLI! Whether you’re fixing bugs, adding features, or improving documentation, your help makes the project better for everyone.

​
Getting Started

1

Fork and clone the repository

git clone https://github.com/vercel-labs/skills.git
cd skills
2

Install dependencies

The project uses pnpm as the package manager:
pnpm install
3

Build the project

pnpm build
4

Test locally

Use the dev script to test changes:
pnpm dev add vercel-labs/agent-skills --list
pnpm dev experimental_sync
pnpm dev check
pnpm dev update
pnpm dev init my-skill

​
Development Workflow

​
Running Tests

# Run all tests
pnpm test

# Run specific test files
pnpm test tests/sanitize-name.test.ts
pnpm test tests/skill-matching.test.ts tests/source-parser.test.ts

# Type check
pnpm type-check

​
Code Formatting

Always run pnpm format before committing changes. CI will fail if code is not properly formatted.
# Format all files
pnpm format

# Check formatting without fixing
pnpm prettier --check .
This project uses Prettier for code formatting to ensure consistency across contributions.

​
Project Architecture

Understanding the codebase structure: 
src/
├── cli.ts           # Main entry point, command routing
├── add.ts           # Core add command logic
├── list.ts          # List installed skills
├── remove.ts        # Remove skills command
├── find.ts          # Search for skills
├── agents.ts        # Agent definitions and detection
├── installer.ts     # Skill installation (symlink/copy)
├── skills.ts        # Skill discovery and parsing
├── skill-lock.ts    # Global lock file management
├── local-lock.ts    # Local lock file management
├── sync.ts          # Sync from node_modules
├── source-parser.ts # Parse git URLs, GitHub shorthand
├── git.ts           # Git clone operations
├── telemetry.ts     # Anonymous usage tracking
└── types.ts         # TypeScript type definitions

​
Adding a New Agent

To add support for a new coding agent:
1

Add agent definition

Edit src/agents.ts and add your agent configuration:
'my-agent': {
  name: 'my-agent',
  displayName: 'My Agent',
  skillsDir: '.myagent/skills',
  globalSkillsDir: join(home, '.myagent/skills'),
  detectInstalled: async () => {
    return existsSync(join(home, '.myagent'));
  },
}
2

Validate the configuration

pnpm run -C scripts validate-agents.ts
3

Sync to README

Update the README.md with your changes:
pnpm run -C scripts sync-agents.ts
4

Test the integration

pnpm dev add vercel-labs/agent-skills --agent my-agent

​
Key Concepts

​
Lock File System

The Skills CLI uses two types of lock files:
Location: ~/.agents/.skill-lock.jsonTracks all globally installed skills with:
  • Source repository
  • Skill path within repository
  • Version hash (skillFolderHash)
  • Install/update timestamps
Version: Currently v3 (includes folder hash for update checking)

​
Update Checking

The check and update commands work by:
  1. Reading ~/.agents/.skill-lock.json for installed skills
  2. Fetching fresh content from GitHub for each skill
  3. Computing the GitHub tree SHA for the skill folder
  4. Comparing with skillFolderHash in lock file
  5. Reporting skills with different hashes as updates
Both commands use forceRefresh: true to bypass caching and ensure accurate update detection. This prevents “phantom updates” from stale cached hashes.

​
Skill Discovery

The CLI searches for skills in multiple locations (see src/skills.ts):
  • Root directory (if contains SKILL.md)
  • skills/ and subdirectories (.curated/, .experimental/, .system/)
  • Agent-specific directories (.claude/skills/, .cursor/skills/, etc.)
  • Plugin manifest declarations (.claude-plugin/marketplace.json)
If no skills found in priority locations, falls back to recursive search.

​
Testing Guidelines

When adding new features:
  • Add test files in tests/ directory
  • Follow existing naming convention: feature-name.test.ts
  • Test both success and failure cases
  • Use test utilities from src/test-utils.ts
  • Use temporary directories for file system tests
  • Clean up test files after each test
  • Test symlink and copy modes separately
  • Verify cross-platform compatibility
  • Test valid and invalid YAML frontmatter
  • Test edge cases (missing fields, wrong types)
  • Test special characters in skill names
  • Test path traversal prevention

​
Pull Request Guidelines

1

Create a focused PR

  • Keep changes focused on a single feature or fix
  • Write clear, descriptive commit messages
  • Reference related issues in PR description
2

Ensure tests pass

pnpm test
pnpm type-check
pnpm format
3

Update documentation

  • Update README.md if adding user-facing features
  • Add comments for complex logic
  • Update AGENTS.md for architecture changes
4

Get review

  • Request review from maintainers
  • Address feedback promptly
  • Be open to suggestions and improvements

​
Code Style

  • Use TypeScript for all code
  • Follow existing patterns in the codebase
  • Prefer async/await over callbacks
  • Use descriptive variable names
  • Add JSDoc comments for exported functions
  • Keep functions small and focused

​
Publishing

Publishing is restricted to maintainers only.
For maintainers, the publish process is: 
# 1. Bump version in package.json
# 2. Build the project
pnpm build

# 3. Publish to npm
npm publish

​
Community

GitHub Issues

Report bugs or request features

Skills Directory

Browse and share skills

Agent Skills Spec

Learn about the specification

Vercel Agent Skills

Example skills repository

​
Questions?

If you have questions about contributing:
  • Check existing GitHub Issues
  • Review the AGENTS.md file for architecture guidance
  • Look at recent pull requests for examples
First time contributing to open source? Check out the GitHub guide to contributing.

Build docs developers (and LLMs) love

Get started for freeTalk to us