qskills (qskills)

一款面向个人开发者的 CLI 技能管理工具，支持多 AI 编程助手的技能、知识库、Agent 配置的统一管理与多源同步。

核心特性

多环境支持 - 支持 Claude Code、Cursor、通义灵码、OpenAI Codex、CodeBuddy Code 等 6 个 AI 环境
一站式管理 - 技能脚本、代码片段、知识笔记、Agent 配置统一管理
多源同步 - 公共资源与私人资源分类同步到 Git 仓库
即取即用 - npx 一键调用，无需全局安装
安全可控 - 敏感信息自动检测，防止意外泄露

快速开始

方式一：npx 直接使用（推荐）

无需安装，直接运行：

# 查看帮助
npx qskills --help

# 初始化配置（首次使用必须）
npx qskills config init

方式二：全局安装

npm install -g qskills
qskills --help

支持的 AI 环境

环境	名称	配置目录	说明
`claude`	Claude Code	`~/.claude`	Anthropic Claude Code
`cursor`	Cursor	`~/.cursor`	Cursor AI 编辑器
`qwen`	通义灵码	`~/.qwen`	阿里云通义灵码
`codex`	OpenAI Codex	`~/.codex`	OpenAI Codex
`codebuddy`	CodeBuddy Code	`~/.codebuddy`	腾讯 CodeBuddy
`common`	通用技能	跨环境共享	适用于所有环境

使用指南

1. 初始化配置

首次使用必须先初始化：

npx qskills config init

按提示完成配置，配置文件位于 ~/.qcli/config.json。

2. 查看可用环境

npx qskills skill envs

输出示例：

┌─────────────┬────────────────┬───────────┬──────────┐
│ 环境        │ 名称           │ 配置目录  │ 状态     │
├─────────────┼────────────────┼───────────┼──────────┤
│ claude      │ Claude Code    │ .claude   │ ✓ 启用   │
│ cursor      │ Cursor         │ .cursor   │ ✓ 启用   │
│ qwen        │ 通义灵码       │ .qwen     │ ✓ 启用   │
│ codex       │ OpenAI Codex   │ .codex    │ ✓ 启用   │
│ codebuddy   │ CodeBuddy Code │ .codebuddy│ ✓ 启用   │
│ common      │ 通用技能       │ (跨环境)  │ ✓ 启用   │
└─────────────┴────────────────┴───────────┴──────────┘

技能管理

短命令：skill 可缩写为 s，如 qskills s add、qskills s list

添加技能

# 基本用法：添加到指定环境
npx qskills skill add ./my-script.js --name my-script --env claude

# 添加文件夹技能
npx qskills skill add ./my-project --name my-project --type folder --env cursor

# 添加到所有环境
npx qskills skill add ./my-tool.js --name my-tool --all

# 完整参数示例
npx qskills skill add ./tool.py \
  --name my-tool \
  --env codebuddy \
  --source private \
  --tags python,automation \
  --description "自动化工具脚本"

参数说明：

参数	简写	必填	说明	默认值
`--name`	`-n`	✓	技能名称	-
`--env`	`-e`	✓	目标环境	common
`--type`	`-t`		single / folder	single
`--source`	`-s`		public / private	private
`--tags`			标签（逗号分隔）	-
`--description`			描述信息	-
`--skip-scan`			跳过安全扫描	false

列出技能

# 列出所有技能
npx qskills skill list

# 筛选特定环境
npx qskills skill list --env cursor

# 筛选特定来源
npx qskills skill list --source public

# 按标签筛选
npx qskills skill list --tags python,automation

# JSON 格式输出（便于脚本处理）
npx qskills skill list --json

复制技能到其他环境

# 将技能从 claude 环境复制到 cursor 环境
npx qskills skill copy my-script --from claude --to cursor

# 从公共库安装到指定环境
npx qskills skill install api-helper --env qwen

删除技能

# 删除技能（需确认）
npx qskills skill remove my-script

# 强制删除（无需确认）
npx qskills skill remove my-script --force

# 指定环境删除
npx qskills skill remove my-script --env claude

知识库管理

短命令：knowledge 可缩写为 k，如 qskills k add、qskills k list

添加知识条目

# 添加文档
npx qskills knowledge add ./article.md \
  --title "API 设计指南" \
  --type document \
  --category api \
  --tags api,design

# 添加代码片段
npx qskills knowledge add ./snippet.js \
  --title "工具函数集合" \
  --type code-snippet \
  --category utils \
  --tags javascript,utils

# 添加项目模板
npx qskills knowledge add ./template/ \
  --title "React 项目模板" \
  --type template \
  --category frontend \
  --tags react,template

知识类型：

类型	说明	用途
`document`	文档	技术文档、笔记
`code-snippet`	代码片段	可复用代码
`template`	模板	项目模板、配置模板
`note`	笔记	快速记录

列出知识条目

# 列出所有
npx qskills knowledge list

# 按类型筛选
npx qskills knowledge list --type code-snippet

# 按分类筛选
npx qskills knowledge list --category api

# 按环境筛选
npx qskills knowledge list --env claude

搜索知识

npx qskills knowledge search "API" --category backend

删除知识条目

npx qskills knowledge remove <id>

Agent 管理

短命令：agent 可缩写为 a，如 qskills a add、qskills a list

添加 Agent 配置

npx qskills agent add ./agent-config/ \
  --name code-reviewer \
  --env claude \
  --tags review,code-quality

列出 Agent

npx qskills agent list --env claude

同步功能

配置远程仓库

# 配置公共仓库
npx qskills config set remotes.public.url https://github.com/user/public-skills.git
npx qskills config set remotes.public.enabled true

# 配置私人仓库
npx qskills config set remotes.private.url git@github.com:user/private-skills.git
npx qskills config set remotes.private.enabled true

执行同步

# 同步所有仓库
npx qskills sync

# 只同步公共仓库
npx qskills sync --source public

# 只同步私人仓库
npx qskills sync --source private

# 预览变更（不实际执行）
npx qskills sync --dry-run

# 强制覆盖本地
npx qskills sync --force

安全扫描

添加技能时自动扫描敏感信息：

检测的敏感信息类型

类型	模式示例	严重级别
AWS Access Key	`AKIA...`	高
GitHub Token	`ghp_...`, `gho_...`	高
私钥文件	`-----BEGIN PRIVATE KEY-----`	高
API Key	`api_key = "..."`	中
JWT Token	`eyJ...`	中
数据库连接	`mysql://user:pass@...`	高
Slack Token	`xox...`	高

扫描示例

npx qskills skill add ./config.js --name my-config

# 若检测到敏感信息：
# ⚠️  Sensitive information detected:
#   [HIGH] aws-access-key in config.js:10
#   [MED] api-key-generic in config.js:15
# 
# Continue anyway? (y/N)

跳过扫描

# 明确跳过（需二次确认）
npx qskills skill add ./public-config.json --name public-config --skip-scan

配置管理

查看配置

# 列出所有配置
npx qskills config list

# 获取单个配置项
npx qskills config get storage.baseDir
npx qskills config get remotes.public.url

修改配置

# 修改存储路径
npx qskills config set storage.baseDir ~/.my-skills

# 启用自动同步
npx qskills config set sync.autoSync true

# 配置同步间隔（分钟）
npx qskills config set sync.syncInterval 30

# 添加扫描跳过规则
npx qskills config set scanner.skipPatterns '["*.md", "docs/**", "test/**"]'

配置文件示例

配置文件位于 ~/.qcli/config.json：

{
  "version": "1.0.0",
  "initialized": true,
  "storage": {
    "baseDir": "~/.qcli/data",
    "skillsDir": "skills",
    "knowledgeDir": "knowledge",
    "agentsDir": "agents"
  },
  "remotes": {
    "public": {
      "url": "https://github.com/user/public-skills.git",
      "branch": "main",
      "enabled": true
    }
  },
  "environments": {
    "enabled": ["claude", "cursor", "qwen", "codex", "codebuddy", "common"],
    "default": "common"
  },
  "sync": {
    "autoSync": false,
    "syncInterval": 0,
    "confirmBeforeSync": true
  },
  "scanner": {
    "enabled": true,
    "skipPatterns": ["*.md", "docs/**"]
  },
  "security": {
    "scanBeforePush": true,
    "warnPublicRepo": true
  }
}

Git 认证配置

方式一：环境变量（推荐）

# Linux/macOS
export QSKILLS_TOKEN=ghp_your_token_here

# Windows CMD
set QSKILLS_TOKEN=ghp_your_token_here

# Windows PowerShell
$env:QSKILLS_TOKEN="ghp_your_token_here"

方式二：SSH 密钥

# 使用 SSH URL
npx qskills config set remotes.private.url git@github.com:user/private-skills.git

创建 GitHub Token

访问 GitHub → Settings → Developer settings → Personal access tokens
点击 "Generate new token (classic)"
勾选 repo 权限
复制 Token 并设置环境变量

存储结构

~/.qcli/
├── config.json              # 配置文件
├── data/
│   ├── index.json           # 本地索引
│   ├── skills/              # 技能存储
│   │   ├── claude/
│   │   │   └── skill-name/
│   │   │       ├── skill.json
│   │   │       └── ...
│   │   ├── cursor/
│   │   ├── qwen/
│   │   ├── codex/
│   │   ├── codebuddy/
│   │   └── common/
│   ├── knowledge/           # 知识库
│   │   ├── claude/
│   │   ├── cursor/
│   │   └── ...
│   └── agents/              # Agent 配置
│       ├── claude/
│       └── ...
├── public-repo/             # 公共仓库克隆
└── private-repo/            # 私人仓库克隆

常见问题

Q: npx 提示找不到命令？

确保 Node.js 版本 >= 16：

node -v

Q: 同步失败，提示认证错误？

设置 GitHub Token：

export QSKILLS_TOKEN=your_token

Q: 如何修改默认存储路径？

npx qskills config set storage.baseDir ~/custom-path

Q: Windows 路径问题？

使用正斜杠：

npx qskills skill add "./scripts/tool.js"

开发与测试

# 克隆仓库
git clone https://github.com/your-username/qskills.git
cd qskills

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 本地运行
node bin/qskills.js --help

许可证

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.bg-shell		.bg-shell
.claude		.claude
bin		bin
docs		docs
scripts		scripts
skills		skills
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
qskills-1.0.0.tgz		qskills-1.0.0.tgz
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

qskills (qskills)

核心特性

快速开始

方式一：npx 直接使用（推荐）

方式二：全局安装

支持的 AI 环境

使用指南

1. 初始化配置

2. 查看可用环境

技能管理

添加技能

列出技能

复制技能到其他环境

删除技能

知识库管理

添加知识条目

列出知识条目

搜索知识

删除知识条目

Agent 管理

添加 Agent 配置

列出 Agent

同步功能

配置远程仓库

执行同步

安全扫描

检测的敏感信息类型

扫描示例

跳过扫描

配置管理

查看配置

修改配置

配置文件示例

Git 认证配置

方式一：环境变量（推荐）

方式二：SSH 密钥

创建 GitHub Token

存储结构

常见问题

Q: npx 提示找不到命令？

Q: 同步失败，提示认证错误？

Q: 如何修改默认存储路径？

Q: Windows 路径问题？

开发与测试

相关文档

许可证

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages