Skill Weaver

Skill Weaver is the consumer-side CLI for managing version-controlled AI skills. A project declares skill repositories in package.json; the weaver clones the requested refs into .skills_cache and writes agent bridge directories such as .windsurf/skills/ and .claude/skills/.

Install

npm install --save-dev skill-weaver

For local development in this package:

npm install
npm run build

Usage

Declare skill dependencies in your application package:

{
  "scripts": {
    "postinstall": "skill-weaver --windsurf"
  },
  "devDependencies": {
    "skill-weaver": "^1.0.0"
  },
  "dependencySkills": {
    "api-researcher": "github:org/api-researcher-skill#v1.0.0",
    "python-analyzer": "org:python-analyzer-skill:main",
    "local-draft": "file:../local-draft-skill"
  }
}

Supported skill source formats:

{
  "dependencySkills": {
    "tagged-skill": "github:owner/repo#v1.0.0",
    "branch-skill": "owner:repo:branch-name",
    "local-skill": "file:../path/to/skill"
  }
}

Local skills can also use local:../path, ../path, ./path, or an absolute path. The handler warns for local skills because they are not reproducible unless maintained in Git with proper version tags.

Supported targets:

skill-weaver
skill-weaver --windsurf
skill-weaver --claude
skill-weaver --windsurf --claude

Running skill-weaver with no target flags generates every supported bridge file.

Package Local Skills

Skill Weaver can also package existing local skill directories and publish them to GitHub with auto-incrementing versions:

skill-weaver --package /path/to/skill-directory

The package command will:

• Analyze the skill directory structure
• Auto-increment the version number
• Create a skill.json manifest file
• Initialize git repository if needed
• Create GitHub repository (if not exists)
• Commit changes with semantic version tag
• Push to GitHub with tags

Expected Skill Layout:

my-skill/
  skill.md          # Required - skill description
  scripts/          # Optional - executable scripts
  docs/             # Optional - documentation
  package.json       # Optional - existing package info

The packager validates that skill.md exists and detects optional scripts/ and docs/ directories.

Each generated bridge contains:

.windsurf/skills/
  api-researcher/
    skill.md
    scripts/

The same layout is used for .claude/skills/.

Expected Skill Layout

Each skill repository must include both skill.md and README.md files. Optional scripts/ directories are referenced in the generated agent context with an absolute path after the skill is fetched.

api-researcher-skill/
  skill.md
  README.md
  scripts/

Development

Running Tests

The project includes a comprehensive test suite:

# Run all tests
npm test

# Run specific test file
npm test -- tests/basic.test.js

# Run tests with coverage
npm test -- --coverage

Project Structure

src/
├── skill-weaver.ts          # Main CLI entry point
└── utils/
    ├── logger.ts           # Centralized logging system
    ├── cli-parser.ts       # CLI argument parsing
    ├── git-operations.ts   # Git command utilities
    ├── github-operations.ts # GitHub CLI interactions
    ├── skill-packager.ts   # Skill packaging & publishing
    └── skill-sync.ts       # Skill synchronization logic

tests/
├── basic.test.js           # Core functionality tests
└── *.test.ts               # Additional test files

Architecture

The codebase follows a modular architecture with:

• Separation of Concerns: Each utility module handles a specific responsibility
• Professional Logging: Configurable logging levels (DEBUG, INFO, WARN, ERROR, SUCCESS, STEP)
• Enhanced Error Handling: Detailed error messages with proper context
• Type Safety: Full TypeScript support with proper type definitions
• Testable Design: Modular structure enables comprehensive unit testing

Build & Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run with coverage
npm test -- --coverage

# Development mode with watch
npm run dev

Logging Configuration

The logging system supports multiple levels and can be configured via environment variables:

# Set log level (default: INFO)
LOG_LEVEL=DEBUG skill-weaver

# Available levels: DEBUG, INFO, WARN, ERROR, SUCCESS, STEP