reskill / rules

---
alwaysApply: true
---

# reskill Development Rules

## Project Overview

reskill is a Git-based package manager for AI agent skills, similar to npm/Go modules. It provides declarative configuration, version locking, and seamless synchronization for managing skills across projects and teams.

**Supported AI Agents:** Cursor, Claude Code, Codex, OpenCode, Windsurf, GitHub Copilot, and more.

## Tech Stack

- **Language:** TypeScript (ES Modules)
- **Runtime:** Node.js >= 18.0.0
- **Build Tool:** Rslib (Rspack-based library bundler)
- **Testing:** Vitest with @vitest/coverage-v8
- **CLI Framework:** Commander.js
- **Linting/Formatting:** Biome
- **Package Manager:** pnpm

## Code Style Guidelines

### Language Requirements

- **Primary Language:** English
- **Comments:** Must be in English only, no Chinese comments allowed
- **Variable/Function Names:** Use English, camelCase for variables and functions
- **Class Names:** PascalCase
- **File Names:** kebab-case for files, e.g., `skill-manager.ts`

### TypeScript Standards

- Use strict TypeScript configuration
- Prefer `type` over `interface` for simple type aliases
- Use explicit return types for public functions
- Use `readonly` for immutable properties
- Avoid `any` type, use `unknown` with type guards instead

```typescript
// Good
export function parseRef(ref: string): ParsedSkillRef { ... }

// Avoid
export function parseRef(ref: string) { ... }
```

### Import Order

1. Node.js built-in modules (with `node:` prefix)
2. External dependencies
3. Internal modules (relative imports)

```typescript
import * as path from 'node:path';
import * as fs from 'node:fs';

import { Command } from 'commander';
import semver from 'semver';

import { SkillManager } from '../core/skill-manager.js';
import type { InstalledSkill } from '../types/index.js';
```

### Error Handling

- Use descriptive error messages in English
- Throw typed errors when possible
- Log errors with appropriate log levels
- Always clean up resources in error cases

```typescript
// Good
if (!exists(skillPath)) {
  throw new Error(`Skill ${name} not found at ${skillPath}`);
}

// Log for user feedback
logger.error(`Failed to install ${name}: ${error.message}`);
```

## Testing Requirements

> **See `.cursor/rules/testing.mdc` for detailed testing guidelines**

### Quick Reference

- **Unit tests** are REQUIRED for all new code (`.test.ts` suffix, same directory)
- **Integration tests** are REQUIRED for CLI commands (`src/cli/commands/__integration__/`)
- **Bug fixes** MUST follow TDD: write failing test first, then fix

```bash
pnpm test              # Unit tests (watch mode)
pnpm test:run          # Unit tests (single run)
pnpm test:integration  # Integration tests (build + run)
```

## Project Architecture

See `.cursor/ARCHITECTURE.md` for detailed architecture documentation.

### Directory Structure

```
src/
├── cli/              # CLI implementation
│   ├── commands/     # Individual command handlers
│   └── index.ts      # CLI entry point
├── core/             # Core business logic
│   ├── skill-manager.ts    # Main orchestrator
│   ├── git-resolver.ts     # Git URL parsing and resolution
│   ├── cache-manager.ts    # Local caching
│   ├── config-loader.ts    # skills.json handling
│   ├── lock-manager.ts     # skills.lock handling
│   ├── installer.ts        # Multi-agent installation
│   ├── agent-registry.ts   # Agent type definitions
│   └── skill-parser.ts     # SKILL.md parsing
├── types/            # TypeScript type definitions
└── utils/            # Shared utilities
    ├── fs.ts         # File system helpers
    ├── git.ts        # Git operations
    └── logger.ts     # Logging utilities
```

### Core Module Responsibilities

- **SkillManager:** Main orchestrator integrating all components
- **GitResolver:** Parse skill references, resolve versions, build repo URLs
- **CacheManager:** Global cache at ~/.reskill-cache
- **ConfigLoader:** Read/write skills.json
- **LockManager:** Read/write skills.lock for version locking
- **Installer:** Handle multi-agent installation (symlink/copy)
- **AgentRegistry:** Define supported agents and their paths

## CLI Development Workflow

**All CLI changes MUST follow the Spec-Driven TDD workflow defined in `docs/cli-spec.md`:**

```
1. SPEC      → Modify docs/cli-spec.md
2. REVIEW    → PR review for spec changes
3. TEST      → Write failing tests (integration + unit)
4. CODE      → Implement minimal code to pass tests
5. REFACTOR  → Improve code quality
6. VERIFY    → pnpm test:run && pnpm test:integration
```

**Key principle:** Never write implementation code before writing tests. The spec defines "what", tests verify "what", code implements "how".

## CLI Command Pattern

Each command follows this structure:

```typescript
import { Command } from 'commander';
import { SkillManager } from '../../core/skill-manager.js';
import { logger } from '../../utils/logger.js';

// Types for command options
interface MyCommandOptions {
  force?: boolean;
}

export const myCommand = new Command('my-command')
  .description('Description in English')
  .argument('[arg]', 'Argument description')
  .option('-f, --force', 'Force operation')
  .action((arg: string | undefined, options: MyCommandOptions) => {
    const manager = new SkillManager(process.cwd());
    try {
      // Command implementation
      logger.success('Operation completed');
    } catch (error) {
      logger.error(`Failed: ${(error as Error).message}`);
      process.exit(1);
    }
  });
```

### CLI Command Testing

When creating or modifying a CLI command, add both unit tests and integration tests. See `.cursor/rules/testing.mdc` for detailed patterns and checklists.

## Git Commit Guidelines

- Write commit messages in English
- Use conventional commit format: `type(scope): description`
- Types: feat, fix, docs, style, refactor, test, chore
- Keep commits focused and atomic
- **Before committing**, check if the change requires:
  - A **changeset** (see Changeset Guidelines below) for any public behavior change
  - A **README update** if CLI commands, options, or output changed
  - A **docs update** if architecture or new concepts were introduced

```
feat(cli): add multi-agent support for install command
fix(cache): handle symlink creation on Windows
test(core): add unit tests for GitResolver
```

## Changeset Guidelines

This project uses [Changesets](https://github.com/changesets/changesets) for version management and publishing.

### When to Add a Changeset

**REQUIRED** - You MUST add a changeset when:
- Adding new features (minor version bump)
- Fixing bugs (patch version bump)
- Making breaking changes (major version bump)
- Any change that affects the public API or behavior

**NOT REQUIRED** - You can skip changeset for:
- Documentation-only changes
- Internal refactoring that doesn't change behavior
- Test-only changes

### Creating a Changeset

After completing your changes, run:

```bash
pnpm changeset
```

Follow the prompts to select:
- **Version type**: `patch` (bug fix), `minor` (new feature), `major` (breaking change)
- **Change description**: Brief summary of your changes

This creates a markdown file in `.changeset/` documenting your changes.

### Changeset File Format

Changeset files should be written in **both English and Chinese** (bilingual) for better accessibility. The format should be **English first, then Chinese**, separated by a horizontal rule (`---`):

```markdown
---
"reskill": minor
---

Brief English summary

**Changes:**
- English change description
- Another change in English

**Bug Fixes:**
- English bug fix description

---

Brief Chinese summary

**Changes:**
- Chinese change description
- Another change in Chinese

**Bug Fixes:**
- Chinese bug fix description
```

### Changeset Content Guidelines

1. **Title**: Brief summary in both English and Chinese (English first, then Chinese)
2. **Structure**: All English content first, then all Chinese content, separated by `---`
3. **Sections**: Use English headers in English section, Chinese headers in Chinese section
4. **Organization**: Organize by category (Changes, Bug Fixes, Backward Compatibility, etc.) in both sections

### Release Workflow

1. **Add Changeset**: Create changeset file with `pnpm changeset`
2. **Submit PR**: Commit changeset file along with your code changes
3. **Merge PR**: When PR is merged to `main`, CI automatically creates a "Version Packages" PR
4. **Review & Merge**: Review the version bump and changelog, then merge the "Version Packages" PR
5. **Auto Publish**: CI automatically publishes to npm after the version PR is merged

### Version Bump Types

| Type | Version Change | Use Case |
|------|----------------|----------|
| `patch` | 0.1.0 → 0.1.1 | Bug fixes, documentation updates |
| `minor` | 0.1.0 → 0.2.0 | New features (backward compatible) |
| `major` | 0.1.0 → 1.0.0 | Breaking changes |

### Common Commands

```bash
# Add changeset (interactive)
pnpm changeset

# Preview version changes (dry run)
pnpm changeset status

# Apply version changes locally (CI handles this automatically)
# IMPORTANT: Use 'pnpm run version' or 'pnpm changeset version', NOT 'pnpm version'
# 'pnpm version' without 'run' is a built-in pnpm command that shows version info
pnpm run version
# or
pnpm changeset version

# Publish to npm (CI handles this automatically)
pnpm release
```

### Release Workflow Checklist

Before merging to `main`, verify:

1. **Changeset exists**: Check `.changeset/` has a new `.md` file (not just config.json and README.md)
2. **Version type is correct**: `patch` / `minor` / `major` matches the change scope
3. **Changeset content**: Description is bilingual (English + Chinese)

After merging to `main`:

1. **CI runs successfully**: Check GitHub Actions for the "Release" workflow
2. **Version PR created**: CI should create a "chore: version packages" PR
3. **Review version PR**: Verify `package.json` version and `CHANGELOG.md` updates
4. **Merge version PR**: This triggers npm publish

### Troubleshooting Release Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| "No changesets found" | Missing changeset file | Run `pnpm changeset` and commit the file |
| "Version already published" | Version not bumped | Add a changeset to trigger version bump |
| "No commits between branches" | `pnpm version` ran instead of `pnpm changeset version` | Use `pnpm changeset version` in CI |
| CI fails to create PR | Missing permissions | Check `GITHUB_TOKEN` permissions in workflow |
| npm publish fails | Missing or invalid token | Check `NPM_TOKEN` secret in repository settings |

## Development Workflow

```bash
# Install dependencies
pnpm install

# Development mode (watch)
pnpm dev

# Build
pnpm build

# Run unit tests (Vitest)
pnpm test

# Run unit tests with coverage
pnpm test:coverage

# Run integration tests (builds first, then tests CLI)
pnpm test:integration

# Type checking
pnpm typecheck

# Manual CLI verification (after build)
node dist/cli/index.js --help
node dist/cli/index.js init -y
node dist/cli/index.js list
```

### Pre-commit Verification

```bash
pnpm test:run && pnpm test:integration && pnpm typecheck && pnpm lint
```

## File Operations

Always use utility functions from `src/utils/fs.ts`:

```typescript
import {
  exists,
  readJson,
  writeJson,
  remove,
  ensureDir,
  createSymlink,
} from '../utils/fs.js';
```

## Logging

Use the logger from `src/utils/logger.ts`:

```typescript
import { logger } from '../utils/logger.js';

logger.info('Processing...');
logger.success('Done!');
logger.warn('Warning message');
logger.error('Error message');
logger.debug('Debug info');  // Only shown with DEBUG env
logger.package('📦 Installing...');  // For package operations
```