---
slug: "universal-skill-kit"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/JiangDing1990/universal-skill-kit@main/README.md"
repo: "https://github.com/JiangDing1990/universal-skill-kit"
source_file: "README.md"
branch: "main"
---
# Universal Skill Kit
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://github.com/JiangDing1990/universal-skill-kit)
[](https://github.com/JiangDing1990/universal-skill-kit)
**Cross-platform AI CLI Skills Development and Conversion Toolkit**
[English](#) | [简体中文](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/README_CN.md)
## ✨ Features
- 🔄 **Smart Conversion** - Bidirectional Claude ↔ Codex conversion with key information preservation
- 📁 **Complete Directory Copy** - 🆕 Automatically copy entire Skill directories with all files and folders
- Recursive scanning of all subdirectories (templates/, scripts/, resources/, docs/, etc.)
- Smart file filtering (excludes node_modules, .git, build files, etc.)
- Preserves directory structure and file permissions
- No need to explicitly reference files in SKILL.md
- ✅ **Automatic Validation** - Pre-conversion quality and completeness checks
- 📦 **Intelligent Compression** - 4 compression strategies, auto-adapting to Codex 500-character limit
- 🎯 **Batch Processing** - Convert multiple Skills at once with parallel processing
- 💡 **Quality Analysis** - Detailed quality scoring and improvement suggestions
- 🎨 **Beautiful Output** - Colorful progress indicators and clear error messages
- ⚡ **High Performance** - 80% faster with parallel batch conversion
## 📖 Quick Start
### Installation
```bash
npm install -g @jiangding/usk-cli
# Or using pnpm
pnpm add -g @jiangding/usk-cli
# Or using yarn
yarn global add @jiangding/usk-cli
```
### Basic Usage
#### 1. Convert a Single Skill
```bash
# Convert to Codex platform
usk convert my-skill/ -t codex -o ./output
# Convert to Claude platform
usk convert my-skill.md -t claude -o ./output
# Use interactive mode
usk convert my-skill/ -t codex --interactive
# With verbose logging
usk convert my-skill/ -t codex --verbose
```
#### 2. Analyze Skill Quality
```bash
# Analyze skill and get recommendations
usk analyze my-skill/
# Output as JSON
usk analyze my-skill/ --json
```
#### 3. Batch Convert
```bash
# Convert all skills in directory
usk batch "skills/**/*.md" -t codex -o ./output
# Use specific compression strategy
usk batch "skills/*/" -t codex -s aggressive
# Parallel processing (default)
usk batch "skills/*/" -t codex --parallel
```
## 🎯 Core Features
### 1. Intelligent Validation System
Automatic quality checks before conversion:
```bash
$ usk convert my-skill/ -t codex
✔ Skill parsed
✔ Validation passed
⚠️ Validation Warnings:
⚠ [description] Description is 888 chars (Codex limit: 500)
ℹ [body] Consider adding code examples
ℹ️ Platform-Specific Notes:
• [description] Will be compressed to 409 chars (53.9% compression)
✔ Conversion completed!
```
**Validation Checks**:
- ❌ **Errors**: Required fields, resource file existence
- ⚠️ **Warnings**: Quality suggestions, formatting issues
- ℹ️ **Platform Notes**: Codex limits, compression requirements
### 2. Multi-File Skills Support
Full support for complex Skill structures:
```
my-skill/
├── SKILL.md # Main file
├── templates/ # Template files
│ └── example.template.md
├── scripts/ # Script files
│ ├── setup.sh
│ └── helper.ts
└── resources/ # Resource files
└── config.yaml
```
Maintains complete directory structure and file permissions after conversion.
### 3. Intelligent Description Compression
4 compression strategies auto-adapt to Codex 500-character limit:
- **Conservative**: Minimal changes, preserves most content
- **Balanced**: Moderate compression, removes example code (recommended)
- **Aggressive**: Maximum compression, extracts keywords
```bash
# Specify compression strategy
usk convert my-skill/ -t codex -s aggressive
```
### 4. Quality Analysis
Get detailed quality scoring and improvement suggestions:
```bash
$ usk analyze my-skill/
📊 Skill Analysis Report
═══════════════════════════════════════════════
Basic Information:
Name: my-skill
Version: 1.0.0
Author: Author Name
Tags: react, typescript
Complexity Analysis:
Level: MEDIUM
Description Length: 450 chars
Has Code Examples: ✓
Technical Keywords:
React, TypeScript, API, GraphQL
Compression Strategy:
Recommended: balanced
Quality Assessment:
Score: 85/100
💡 Suggestions:
⚡ Add author information for better attribution
ℹ Consider adding more code examples
```
### 5. Performance Optimization
Parallel batch conversion for maximum efficiency:
```bash
$ usk batch "skills/**/*.md" -t codex
Converting 1/20: skill-1.md
Converting 2/20: skill-2.md
Converting 3/20: skill-3.md
...
✔ Converted all 20 skills successfully in 4s!
Performance: 80% faster with 5-file parallel processing
```
### 6. Enhanced Error Handling
Friendly error messages with actionable suggestions:
```bash
$ usk convert non-existent/
❌ Error:
[SKILL_NOT_FOUND] Skill not found: non-existent/SKILL.md
💡 Suggestions:
• Ensure the file path is correct
• If it's a directory, make sure it contains SKILL.md
• Use absolute path or path relative to current working directory
```
## 🏗️ Project Structure
```
universal-skill-kit/
├── packages/
│ ├── core/ # @usk/core - Core conversion engine
│ │ ├── parser/ # Skill parser
│ │ ├── optimizer/ # Smart compressor
│ │ ├── analyzer/ # Quality analyzer
│ │ ├── validator/ # Validator ✨
│ │ ├── converter/ # Converter (multi-file support)
│ │ ├── errors/ # Error handling ✨ NEW
│ │ └── constants/ # Constants ✨ NEW
│ ├── cli/ # @usk/cli - Command-line tool
│ └── utils/ # @usk/utils - Utilities
│ ├── path-mapper/ # Path mapping
│ └── logger/ # Logging system ✨ NEW
├── docs/ # Documentation
└── examples/ # Examples
```
## 📊 Test Coverage
```
Overall Coverage: 92.11%
─────────────────────────────
Utils (Logger): 100% ⭐⭐⭐
Utils (PathMapper): 100% ⭐⭐⭐
Optimizer Strategies: 99.67% ⭐⭐
Validator: 97.75% ⭐⭐
Analyzer: 96.01% ⭐
Optimizer: 94.79% ⭐
Parser: 84.61%
Converter: 84.00%
─────────────────────────────
Tests Passing: 281/281 ✅
```
## 🔧 API Usage
### Using Core APIs
```typescript
import { SkillConverter, SkillValidator, SkillAnalyzer } from '@jiangding/usk-core'
// 1. Validate Skill
const validator = new SkillValidator()
const validation = await validator.validate(skill, skillPath)
if (!validation.valid) {
console.log('Errors:', validation.errors)
}
// 2. Analyze Skill
const analyzer = new SkillAnalyzer()
const report = analyzer.analyze(skill)
console.log('Quality Score:', report.estimatedQuality)
console.log('Recommended Strategy:', report.recommendedStrategy)
// 3. Convert Skill
const converter = new SkillConverter()
const result = await converter.convert(skillPath, {
targetPlatform: 'codex',
outputDir: './output',
compressionStrategy: 'balanced',
verbose: true // Enable detailed logs
})
console.log('Conversion successful:', result.success)
console.log('Output:', result.outputPath)
console.log('Compression rate:', result.statistics.compressionRate)
```
### Batch Conversion with Progress Callback
```typescript
const results = await converter.convertBatch(
files,
options,
(current, total, skillPath) => {
console.log(`Converting ${current}/${total}: ${skillPath}`)
}
)
```
## 🎨 CLI Options
### convert Command
```bash
usk convert [options]
Options:
-t, --target Target platform (claude|codex) [default: codex]
-o, --output Output directory
-s, --strategy Compression strategy (conservative|balanced|aggressive)
-i, --interactive Interactive mode
--verbose Show detailed logs
```
### analyze Command
```bash
usk analyze [options]
Options:
-v, --verbose Show detailed analysis
--json Output as JSON
```
### batch Command
```bash
usk batch [options]
Options:
-t, --target Target platform [default: codex]
-o, --output Output directory
-s, --strategy Compression strategy
--parallel Enable parallel processing [default: true]
--verbose Show detailed logs
```
## 🌟 Highlights
### Automatic Validation
Pre-conversion Skill quality checks:
- Validates required fields (name, description, body)
- Verifies resource file existence
- Detects common issues (empty links, TODO markers, etc.)
- Platform-specific requirement checks (Codex 500-character limit)
### Intelligent Compression
Compresses descriptions while preserving key technical information:
- Extracts technical keywords (version numbers, framework names, etc.)
- Removes redundant example code
- Simplifies verbose expressions
- Intelligent truncation maintaining sentence integrity
### Multi-File Support
Complete support for complex Skill structures:
- Recursively copies all resource files
- Maintains directory structure and relative paths
- Preserves script file permissions (755)
- Warning messages for missing files
### Performance Optimization
- **Parallel Processing**: Default 5-file concurrency
- **80% Faster**: Batch conversion of 20 Skills: 20s → 4s
- **Real-time Progress**: Live updates during batch conversion
- **Smart Error Handling**: Individual failures don't block batch operations
## 📝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/CONTRIBUTING.md) for details.
## 📄 License
[MIT](https://github.com/JiangDing1990/universal-skill-kit/tree/HEAD/LICENSE)
## 🔗 Related Links
- [Technical Design](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/docs/TECHNICAL_DESIGN.md)
- [Development Roadmap](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/docs/ROADMAP.md)
- [Changelog](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/CHANGELOG.md)
- [Contributing Guide](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/CONTRIBUTING.md)
- [User Guide](https://github.com/JiangDing1990/universal-skill-kit/blob/HEAD/docs/USER_GUIDE.md)
## 💬 Feedback
Have questions or suggestions? Please submit an [Issue](https://github.com/JiangDing1990/universal-skill-kit/issues)
---
Made with ❤️ by [JiangDing1990](https://github.com/JiangDing1990)