SkCC - 用户使用手册

版本: 1.0.0 最后更新: 2026-04-04

1. 简介

1.1 什么是SkCC?

SkCC 是一个工业级的多目标编译器，将统一的 SKILL.md 规范转换为平台特定的 AI Agent 指令。采用三段式编译架构：

Frontend (前端): YAML解析、类型验证、权限审计、MCP依赖检查
Mid-end (中端): SkillIR中间表示、Anti-Skill注入优化、安全等级分析
Backend (后端): 多平台代码生成 (Claude/Codex/Gemini)

1.2 核心特性

特性	描述
三段式编译架构	Frontend → Mid-end → Backend
多目标编译	一次编写，多平台使用
安全验证	内置权限审计和Anti-Skill注入
语义保持	编译后保持原始skill语义
错误诊断	详细的错误报告和修复建议
性能优化	编译后skill执行速度提升16.9%

1.3 系统要求

组件	要求
操作系统	Linux / macOS / Windows (WSL2)
Rust	1.75+ (Edition 2024)
Node.js	14+ (可选，用于npm安装)
内存	最低 512MB
磁盘	最低 50MB

2. 安装指南

2.1 通过 npm 安装 (推荐 Node.js 用户)

# 全局安装
npm install -g nexa-skill-compiler

# 安装 Rust 二进制 (必需)
cargo install nexa-skill-cli

2.2 通过 Cargo 安装 (推荐 Rust 用户)

# 从 crates.io 安装
cargo install nexa-skill-cli

2.3 从源码安装

# 克隆仓库
git clone https://github.com/ouyangyipeng/Skill-Compiler.git
cd Skill-Compiler

# 构建发布版本
cargo build --release

# 安装到系统
cargo install --path nexa-skill-cli

2.4 VS Code 扩展

在 VS Code 扩展市场搜索 "SkCC" 安装。

2.5 验证安装

# 检查版本
nsc --version

# 查看帮助
nsc --help

2.3 开发环境设置

# 安装开发依赖
rustup component add rustfmt clippy

# 运行测试
cargo test

# 代码格式化
cargo fmt

# 代码检查
cargo clippy

3. 快速开始

3.1 创建第一个Skill

# 初始化新skill
nexa-skill init my-first-skill

# 进入目录
cd my-first-skill

# 查看生成的文件
ls -la

生成的目录结构：

my-first-skill/
├── SKILL.md          # Skill定义文件
├── examples/         # 示例目录
│   └── example1.md
└── tests/           # 测试目录
    └── test1.md

3.2 编译Skill

# 编译到Claude格式
nexa-skill build SKILL.md --target claude

# 编译到所有平台
nexa-skill build SKILL.md --target all

# 查看输出
ls -la dist/

3.3 验证Skill

# 检查skill语法
nexa-skill check SKILL.md

# 验证skill完整性
nexa-skill validate SKILL.md

4. 命令参考

4.1 `build` - 编译Skill

语法:

nexa-skill build [OPTIONS] <INPUT>

参数:

参数	简写	描述	默认值
`--target`	`-t`	目标平台	`claude`
`--output`	`-o`	输出目录	`dist/`
`--config`	`-c`	配置文件	`.nsc.toml`

目标平台:

claude - Claude (Anthropic)
codex - GPT/Codex (OpenAI)
gemini - Gemini (Google)
all - 所有平台

示例:

# 编译单个文件到Claude
nexa-skill build SKILL.md --target claude

# 编译目录到所有平台
nexa-skill build ./skills/ --target all

# 指定输出目录
nexa-skill build SKILL.md --output ./compiled/

4.2 `check` - 检查Skill

语法:

nexa-skill check [OPTIONS] <INPUT>

参数:

参数	简写	描述	默认值
`--format`	`-f`	输出格式	`text`

输出格式:

text - 人类可读文本
json - JSON格式

示例:

# 检查skill
nexa-skill check SKILL.md

# JSON输出
nexa-skill check SKILL.md --format json

4.3 `validate` - 验证Skill

语法:

nexa-skill validate [OPTIONS] <INPUT>

参数:

参数	简写	描述	默认值
`--strict`	`-s`	严格模式	`false`

示例:

# 基本验证
nexa-skill validate SKILL.md

# 严格模式
nexa-skill validate SKILL.md --strict

4.4 `init` - 初始化Skill

语法:

nexa-skill init [OPTIONS] <NAME>

参数:

参数	简写	描述	默认值
`--author`	`-a`	作者名称	环境变量
`--template`	`-t`	模板类型	`basic`

模板类型:

basic - 基础模板
advanced - 高级模板（包含权限、安全级别等）
mcp - MCP集成模板

示例:

# 创建基础skill
nexa-skill init my-skill

# 创建高级skill
nexa-skill init my-skill --template advanced

# 指定作者
nexa-skill init my-skill --author "Your Name"

4.5 `list` - 列出Skills

语法:

nexa-skill list [OPTIONS]

参数:

参数	简写	描述	默认值
`--path`	`-p`	搜索路径	当前目录
`--filter`	`-f`	过滤条件	无

示例:

# 列出当前目录所有skills
nexa-skill list

# 指定搜索路径
nexa-skill list --path ./skills/

# 过滤特定类型
nexa-skill list --filter "security_level:high"

4.6 `clean` - 清理输出

语法:

nexa-skill clean [OPTIONS]

参数:

参数	简写	描述	默认值
`--output`	`-o`	输出目录	`dist/`
`--dry-run`	`-n`	预览模式	`false`

示例:

# 清理输出目录
nexa-skill clean

# 预览删除内容
nexa-skill clean --dry-run

5. Skill规范

5.1 文件结构

Skill文件使用Markdown格式，包含YAML前置数据：

---
name: skill-name
description: Skill description
version: "1.0.0"
author: Your Name
security_level: medium
permissions:
  - kind: file_read
    scope: "workspace/**"
mcp_servers:
  - name: filesystem
    required: true
---

# Skill Name

## Description
Detailed description of the skill...

## Procedures
1. Step one
2. Step two
3. Step three

## Examples
### Example 1: Basic Usage
...

5.2 必填字段

字段	类型	描述	示例
`name`	string	Skill唯一标识符	`my-skill`
`description`	string	简短描述	`A sample skill`

5.3 可选字段

字段	类型	描述	默认值
`version`	string	语义版本	`1.0.0`
`author`	string	作者名称	-
`security_level`	enum	安全级别	`low`
`permissions`	array	权限列表	`[]`
`mcp_servers`	array	MCP服务器依赖	`[]`
`hitl_required`	boolean	是否需要人工确认	`false`

5.4 安全级别

级别	描述	HITL要求
`low`	只读操作，无副作用	不需要
`medium`	中等风险操作	可选
`high`	高风险操作	需要
`critical`	不可逆操作	始终需要

5.5 权限声明

permissions:
  - kind: file_read
    scope: "workspace/**"
  - kind: file_write
    scope: "workspace/output/**"
  - kind: network_request
    scope: "api.example.com/*"

权限类型:

类型	描述
`file_read`	文件读取权限
`file_write`	文件写入权限
`network_request`	网络请求权限
`command_execute`	命令执行权限
`database_access`	数据库访问权限

6. 配置选项

6.1 配置文件

SkCC使用TOML格式的配置文件 .nsc.toml：

# .nsc.toml

[compiler]
default_target = "claude"
output_dir = "dist"
strict_mode = false

[security]
mcp_whitelist = ["filesystem", "github"]
allow_undeclared_mcp = false
high_risk_keywords = ["rm -rf", "drop table", "delete from"]

[output]
generate_manifest = true
generate_schema = true
pretty_print = true

6.2 环境变量

变量	描述	默认值
`SKCC_DEFAULT_TARGET`	默认目标平台	`claude`
`SKCC_OUTPUT_DIR`	输出目录	`dist`
`SKCC_CONFIG_PATH`	配置文件路径	`.nsc.toml`
`SKCC_LOG_LEVEL`	日志级别	`info`

6.3 命令行优先级

配置优先级（从高到低）：

命令行参数
环境变量
配置文件
默认值

7. 输出格式

7.1 Claude输出

# skill-name

## Description
Skill description...

## Security Level
MEDIUM

## Permissions Required
- file_read: workspace/**

## Procedures
1. Step one
2. Step two

## Constraints
- Do not modify files without confirmation
- Always validate input before processing

7.2 Codex输出

{
  "name": "skill-name",
  "description": "Skill description...",
  "parameters": {
    "type": "object",
    "properties": {
      "input": { "type": "string" }
    }
  },
  "security": {
    "level": "medium",
    "permissions": ["file_read"]
  }
}

7.3 Gemini输出

name: skill-name
description: Skill description...
security_level: MEDIUM
procedures:
  - step: 1
    action: Step one
  - step: 2
    action: Step two

7.4 Manifest文件

每次编译会生成 manifest.json：

{
  "version": "1.0.0",
  "compiled_at": "2026-04-04T00:00:00Z",
  "source_hash": "abc123...",
  "targets": {
    "claude": {
      "file": "skill-name.md",
      "size": 1234
    },
    "codex": {
      "file": "skill-name.json",
      "size": 567
    }
  }
}

8. 高级用法

8.1 批量编译

# 编译目录下所有skills
nexa-skill build ./skills/ --target all

# 使用通配符
nexa-skill build ./skills/**/*.md --target claude

8.2 增量编译

# 只编译修改过的文件
nexa-skill build ./skills/ --incremental

8.3 自定义模板

# 使用自定义模板
nexa-skill build SKILL.md --template ./templates/custom/

8.4 集成CI/CD

# .github/workflows/compile-skills.yml
name: Compile Skills

on:
  push:
    paths:
      - 'skills/**'

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          
      - name: Install SkCC
        run: cargo install --path nexa-skill-cli
        
      - name: Compile Skills
        run: nexa-skill build ./skills/ --target all
        
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: compiled-skills
          path: dist/

9. 故障排除

9.1 常见错误

错误: Missing required field 'name'

原因: Skill文件缺少必填字段
解决: 在frontmatter中添加 name 字段

---
name: my-skill
description: My skill
---

错误: Invalid security level

原因: 安全级别值无效
解决: 使用有效的安全级别: low, medium, high, critical

错误: Permission scope format invalid

原因: 权限范围格式不正确
解决: 使用glob格式: workspace/**, output/*.json

9.2 调试模式

# 启用详细日志
RUST_LOG=debug nexa-skill build SKILL.md

# 查看编译过程
nexa-skill build SKILL.md --verbose

9.3 获取帮助

# 命令帮助
nexa-skill help build

# 查看版本信息
nexa-skill --version

10. 最佳实践

10.1 Skill设计原则

单一职责: 每个skill只做一件事
明确描述: 描述要清晰、具体
合理权限: 只请求必要的权限
安全优先: 选择合适的安全级别

10.2 文件组织

skills/
├── document/
│   ├── pdf-processor/
│   │   └── SKILL.md
│   └── word-processor/
│       └── SKILL.md
├── code/
│   ├── python-analyzer/
│   │   └── SKILL.md
│   └── typescript-linter/
│       └── SKILL.md
└── data/
    ├── csv-processor/
    │   └── SKILL.md
    └── json-transformer/
        └── SKILL.md

10.3 版本控制

# 使用语义版本
version: "1.0.0"  # 主版本.次版本.修订版本

# 在skill文件中记录变更
## Changelog
### v1.0.0 (2026-04-04)
- Initial release

10.4 测试策略

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_skill_parsing

# 运行集成测试
cargo test --test integration

11. API参考

11.1 Rust API

use nexa_skill_core::{Compiler, CompilerConfig, TargetPlatform};

// 创建编译器
let config = CompilerConfig::default();
let compiler = Compiler::new(config);

// 编译文件
let output = compiler.compile_file("SKILL.md", vec![TargetPlatform::Claude])?;

// 访问输出
println!("Output: {}", output.content);

11.2 Python API

from nexa_skill import Compiler, Target

# 创建编译器
compiler = Compiler()

# 编译skill
result = compiler.compile("SKILL.md", target=Target.CLAUDE)

# 访问结果
print(result.content)

12. 常见问题

Q: SkCC支持哪些平台？

A: 目前支持Claude、GPT/Codex和Gemini三个平台。

Q: 如何添加新的目标平台？

A: 实现 Emitter trait并注册到编译器：

pub trait Emitter: Send + Sync {
    async fn emit(&self, ir: &ValidatedSkillIR) -> Result<String, EmitError>;
    fn file_extension(&self) -> &'static str;
    fn output_format(&self) -> &'static str;
}

Q: 编译后的skill性能如何？

A: 根据大规模实验，编译后的skill执行速度比原始skill快16.9%。

Q: 如何处理敏感信息？

A: 使用环境变量或配置文件，不要在skill文件中硬编码敏感信息。

Q: 支持国际化吗？

A: Skill内容支持任何语言，但元数据字段名称必须使用英文。

附录

A. 完整示例

---
name: document-summarizer
description: Summarizes documents using AI
version: "1.0.0"
author: SkCC Team
security_level: low
permissions:
  - kind: file_read
    scope: "documents/**"
---

# Document Summarizer

## Description
This skill reads documents and generates concise summaries using AI analysis.

## Triggers
- User requests a document summary
- Document needs to be condensed for quick review

## Procedures

1. **Read Document**
   - Open the specified document file
   - Extract text content
   - Handle different formats (PDF, DOCX, TXT)

2. **Analyze Content**
   - Identify key topics and themes
   - Extract important sentences
   - Determine document structure

3. **Generate Summary**
   - Create concise summary (max 200 words)
   - Include key points as bullet list
   - Preserve important numbers and dates

## Examples

### Example 1: PDF Summary
**Input:** `report.pdf`
**Output:**

Summary: Q3 Financial Report

Key Points:

Revenue increased 15% YoY
Operating margin improved to 22%
New product launch scheduled Q4


## Constraints
- Maximum input file size: 10MB
- Supported formats: PDF, DOCX, TXT, MD
- Summary length: 100-200 words

## Fallbacks
- If file too large: Split and summarize parts
- If format unsupported: Return error with suggestions

B. 参考链接

文档版本: 1.0.0
最后更新: 2026-04-04 维护者: SkCC Team

Uh oh!

FilesExpand file tree

USER_GUIDE.md

Latest commit

History

USER_GUIDE.md

File metadata and controls

SkCC - 用户使用手册

目录

1. 简介

1.1 什么是SkCC?

1.2 核心特性

1.3 系统要求

2. 安装指南

2.1 通过 npm 安装 (推荐 Node.js 用户)

2.2 通过 Cargo 安装 (推荐 Rust 用户)

2.3 从源码安装

2.4 VS Code 扩展

2.5 验证安装

2.3 开发环境设置

3. 快速开始

3.1 创建第一个Skill

3.2 编译Skill

3.3 验证Skill

4. 命令参考

4.1 build - 编译Skill

4.2 check - 检查Skill

4.3 validate - 验证Skill

4.4 init - 初始化Skill

4.5 list - 列出Skills

4.6 clean - 清理输出

5. Skill规范

5.1 文件结构

5.2 必填字段

5.3 可选字段

5.4 安全级别

5.5 权限声明

6. 配置选项

6.1 配置文件

6.2 环境变量

6.3 命令行优先级

7. 输出格式

7.1 Claude输出

7.2 Codex输出

7.3 Gemini输出

7.4 Manifest文件

8. 高级用法

8.1 批量编译

8.2 增量编译

8.3 自定义模板

8.4 集成CI/CD

9. 故障排除

9.1 常见错误

错误: Missing required field 'name'

错误: Invalid security level

错误: Permission scope format invalid

9.2 调试模式

9.3 获取帮助

10. 最佳实践

10.1 Skill设计原则

10.2 文件组织

10.3 版本控制

10.4 测试策略

11. API参考

11.1 Rust API

11.2 Python API

12. 常见问题

Q: SkCC支持哪些平台？

Q: 如何添加新的目标平台？

Q: 编译后的skill性能如何？

Q: 如何处理敏感信息？

Q: 支持国际化吗？

附录

A. 完整示例

B. 参考链接

4.1 `build` - 编译Skill

4.2 `check` - 检查Skill

4.3 `validate` - 验证Skill

4.4 `init` - 初始化Skill

4.5 `list` - 列出Skills

4.6 `clean` - 清理输出