v-skills

Turn your node_modules into AI superpowers.

Your dependencies already have amazing documentation - READMEs, changelogs, TypeScript definitions, API docs. Why make your AI agent fetch them from the internet every time?

v-skills extracts everything useful from your installed packages and creates unified skill files that AI agents (like Claude) can use instantly as context.

npx v-skills
# ✓ Generated 247 skill files in 892ms

Why v-skills?

| Without v-skills | With v-skills | |------------------------------|----------------------------------------| | AI guesses API signatures | AI knows exact types from your version | | "Check the docs" responses | Accurate, contextual answers | | Outdated examples | Examples from your installed version | | Manual doc maintenance | Zero maintenance, auto-syncs | | Context7 API calls per query | Local, instant, always available |

What It Extracts

v-skills doesn't just copy READMEs. It creates unified SKILL.md files gathering:

| Source | What's Extracted | |-----------------------------------|----------------------------------------------------| | README.md | Full documentation | | CHANGELOG.md | Recent changes (last 50 lines) | | LICENSE | License type detection | | package.json | Version, description, engines, peer deps, keywords | | docs/ folder | Links to all documentation files | | *.d.ts files | Links to TypeScript definitions | | @types/* | DefinitelyTyped package detection | | CONTRIBUTING.md, API.md, etc. | Additional documentation |

Install

npm install v-skills --save-dev

Zero dependencies. Just Node.js >=18. No bloat.

Quick Start

# Generate all skills
npx v-skills

# Only your direct dependencies (skip transitive)
npx v-skills --direct-only

# Exclude dev tooling noise
npx v-skills --exclude "typescript,eslint*,@types/*,prettier"

Output Structure

.claude/skills/v-skills/
├── CLAUDE.md                    # Instructions for Claude Code AI
├── _index.md                    # Searchable index with descriptions & keywords
├── react/
│   └── SKILL.md
├── express/
│   └── SKILL.md
├── zod/
│   └── SKILL.md
└── @tanstack/
    └── query/
        └── SKILL.md             # Scoped packages preserve structure

The CLAUDE.md file instructs Claude Code to check the _index.md first before opening individual SKILL.md files, improving efficiency when working with projects that have many dependencies.

Example SKILL.md

<!-- v-skills: [email protected] -->
# react

**Version:** 18.3.1
**Description:** React is a JavaScript library for building user interfaces.
**Repository:** https://github.com/facebook/react
**Homepage:** https://react.dev/
**License:** MIT
**Engines:** node: >=0.10.0
**Peer Dependencies:** react-dom@^18.0.0

---

## Documentation

# React

React is a JavaScript library for building user interfaces.

## Installation
npm install react

## Usage
import React from 'react';
...

## Additional Resources

### Local Documentation
- [CHANGELOG.md](../node_modules/react/CHANGELOG.md)
- [CONTRIBUTING.md](../node_modules/react/CONTRIBUTING.md)

### Official Documentation
- [https://react.dev/](https://react.dev/)

### API Reference
- [TypeScript Definitions](../node_modules/@types/react/index.d.ts)

## Recent Changes

### 18.3.1
- Fix: edge case in concurrent rendering
- Fix: memory leak in useEffect cleanup
...

## Keywords

react, javascript, ui, frontend, components

---
*Auto-generated by v-skills on 2025-01-15. Do not edit manually.*

Workspace Support

v-skills automatically detects and handles:

| Workspace Type | Detection | |----------------|-----------------------------------------| | npm | package.json workspaces field | | yarn | package.json workspaces + yarn.lock | | pnpm | pnpm-workspace.yaml | | Lerna | lerna.json | | Nx | nx.json | | Turborepo | Via npm/yarn/pnpm workspaces |

Monorepo packages (symlinked in node_modules) are fully supported.

Auto-Sync with postinstall

Add to your package.json and forget about it:

{
  "scripts": {
    "postinstall": "v-skills --silent"
  }
}

Skills regenerate automatically whenever dependencies change.

Configuration

v-skills works out of the box, but you can customize it.

Config File (optional)

npx v-skills init

Creates v-skills.config.mjs:

/** @type {import('v-skills').VSkillsConfig} */
export default {
  // Only direct dependencies (recommended for large projects)
  directOnly: true,

  // Packages to include (supports globs)
  include: ['react', 'express', '@tanstack/*'],

  // Packages to exclude (supports globs)
  exclude: [
    '@types/*',      // TypeScript types (linked automatically)
    'typescript',    // Dev tooling
    'eslint*',       // Linting
    'prettier',      // Formatting
    '*-loader',      // Webpack loaders
    '*-plugin',      // Build plugins
  ],

  // Output directory (default: .claude/skills/v-skills)
  output: '.claude/skills/v-skills',
};

Config Formats

v-skills automatically detects (in order):

1. v-skills.config.mjs / .js / .cjs
2. v-skills.config.json
3. v-skills.config.yaml / .yml
4. package.json → "vskills" field

CLI Options

v-skills [command] [options]

Commands:
  generate          Generate skill files (default)
  clean             Remove generated files
  init              Create config template
  help              Show help

Options:
  --cwd <path>      Working directory
  --output <path>   Output directory
  --direct-only     Only direct dependencies
  --include <pkgs>  Comma-separated packages to include
  --exclude <pkgs>  Comma-separated packages to exclude
  --silent          Suppress output (for scripts)
  --no-config       Ignore config file

CLI options override config file settings.

Programmatic API

import { generate, clean, loadConfig } from 'v-skills';

// Generate with options
const result = await generate({
  cwd: process.cwd(),
  directOnly: true,
  exclude: ['@types/*', 'eslint*'],
});

console.log(`Generated ${result.skills.length} skills`);
console.log(`Workspace: ${result.workspaceType}`);
console.log(`Duration: ${result.duration}ms`);

// Clean up
await clean();

Exported Types

import type {
  GenerateOptions,
  GenerateResult,
  SkillFile,
  PackageInfo,
  DocumentationSources,
  WorkspaceInfo,
  VSkillsConfig,
} from 'v-skills';

Git Integration

v-skills automatically adds the output directory to .gitignore on first run.

Skills are generated from node_modules - no need to commit them. Each developer/CI environment generates their own from installed packages.

Performance

| Project Size | Packages | Time | |----------------|----------|--------| | Small | ~50 | <200ms | | Medium | ~200 | ~500ms | | Large monorepo | ~2000+ | ~2-3s |

Recommended Excludes

For cleaner output, exclude dev tooling:

exclude: [
  // TypeScript (types are linked, not copied)
  '@types/*',
  'typescript',

  // Linting & formatting
  'eslint*',
  '@eslint/*',
  'prettier',

  // Build tools
  '*-loader',
  '*-plugin',
  'webpack*',
  'vite',
  'rollup',
  'esbuild',

  // Testing
  'jest',
  'vitest',
  '@testing-library/*',
  'cypress',
]

How It Works

1. Detect workspace - Finds npm/yarn/pnpm/lerna/nx configuration
2. Traverse node_modules - Walks all packages (including symlinked workspace packages)
3. Gather documentation - Extracts README, changelog, license, types, docs/
4. Generate SKILL.md - Creates unified skill file per package
5. Create index - Generates searchable _index.md with all packages
6. Update .gitignore - Ensures output isn't committed

License

MIT

Stop making your AI guess. Give it the docs.

npx v-skills