gsc-skills

Lenovo GSC Basic 的 Skills 命令行工具。

快速开始

一次性执行（推荐）：

pnpx gsc-skills --help
pnpx gsc-skills add gsc-basic-group/gsc-basic-skills

也支持完整 GitLab 地址：

pnpx gsc-skills add https://gitlab.xpaas.lenovo.com/<group>/<repo>

全局安装后可直接使用：

pnpm add -g gsc-skills
gsc-skills --help

团队推荐：

• 日常使用优先 pnpx gsc-skills ...，减少全局环境差异。
• 需要频繁调用时再全局安装，统一使用 gsc-skills 命令。

常用命令

gsc-skills add <source>          # 安装 skill 源
gsc-skills list                  # 查看已安装 skills
gsc-skills remove                # 删除已安装 skills
gsc-skills update                # 更新已安装 skills
gsc-skills init [name]           # 初始化一个 skill 模板
gsc-skills experimental_sync     # 从 node_modules 同步
gsc-skills experimental_install  # 从锁文件恢复

说明：

• source 支持 <group>/<repo> 与 https://gitlab.xpaas.lenovo.com/<group>/<repo>。
• 使用 --help 可查看每个命令的完整选项。

Agent 参数说明

• --agent（-a）支持以下值： github-copilot、claude-code、openclaw、cursor、gemini-cli、kimi-cli、opencode、qwen-code。
• 支持通配符 * 表示所有受支持 agent。
• 当未传 --agent 时，默认使用 github-copilot。
• 适用命令：add、experimental_sync（安装目标）、remove、list（过滤目标）。

与上游差异

• 当前仅支持 Lenovo GitLab 源：gitlab.xpaas.lenovo.com。
• 项目级锁文件名为 gsc-basic-skills-lock.json。
• npm 包名是 gsc-skills，可执行命令为 gsc-skills。

兼容性说明：

• 旧版本在部分 pnpm 场景下可能出现多 bin 解析冲突。
• 新版本已补齐 gsc-skills 可执行入口，推荐升级到最新版本。

国内网络安装指引（无法访问 npm registry）

如果当前网络无法稳定访问 registry.npmjs.org，可使用镜像或企业私有源。

临时使用镜像（单次命令）：

pnpx --registry=https://registry.npmmirror.com gsc-skills --help
pnpx --registry=https://registry.npmmirror.com gsc-skills add gsc-basic-group/gsc-basic-skills

持久配置镜像（当前用户）：

npm config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

如果公司有私有 npm 源（Nexus/Artifactory/Verdaccio），建议优先配置私有源，再由私有源代理公网包。

排查建议：

• npm ping --registry=<your-registry> 验证连通性。
• pnpm store prune 清理异常缓存后重试。
• 若仅 pnpx 失败，可改用 pnpm dlx --package=gsc-skills gsc-skills --help 交叉验证。

安装范围

• 默认安装到当前项目（project scope）。
• 使用 -g 或 --global 安装到用户级目录（global scope）。
• 对于通用 agent，项目内默认目录是 .agents/skills。

指定扫描目录

add 命令支持 --scan-dir，用于限制 skill 发现范围，只扫描你指定的目录。

示例：

gsc-skills add <source> --scan-dir shared/skills
gsc-skills add <source> --scan-dir shared/skills backend/skills
gsc-skills add <source> --scan-dir shared/skills --scan-dir backend/skills

说明：

• --scan-dir 可重复传入，也支持一次传多个目录。
• 目录路径相对仓库根目录（或 source 的 subpath）。
• 若传入 --scan-dir 但未提供目录值，命令会直接报错。

Post-install Hook（安装后处理）

add 命令支持在安装完成后执行本地 hook 命令，适合从 clone 下来的仓库中复制额外文件。

示例：

gsc-skills add <source> \
	--post-install-hook "node scripts/post-install.js"

如果希望 hook 失败时让命令直接失败，可加严格模式：

gsc-skills add <source> \
	--post-install-hook "node scripts/post-install.js" \
	--hook-strict

说明：

• hook 在 skill 安装完成后执行。
• hook 执行后，临时 clone 目录会按既有流程 cleanup。
• 默认模式下 hook 失败仅告警，不会回滚已安装的 skill；--hook-strict 下会返回失败。

Hook 可用环境变量

• GSC_SKILLS_HOOK_EVENT：固定为 post-install
• GSC_SKILLS_CLONE_DIR：临时 clone 目录
• GSC_SKILLS_SOURCE_INPUT：用户输入的 source
• GSC_SKILLS_SOURCE_URL：解析后的 source URL
• GSC_SKILLS_SOURCE_REF：source ref（如有）
• GSC_SKILLS_SOURCE_SUBPATH：source subpath（如有）
• GSC_SKILLS_INSTALL_SCOPE：project 或 global
• GSC_SKILLS_INSTALL_MODE：copy 或 symlink
• GSC_SKILLS_TARGET_AGENTS_JSON：目标 agents（JSON 数组）
• GSC_SKILLS_SELECTED_SKILLS_JSON：用户选中的 skill 名称（JSON 数组）
• GSC_SKILLS_SUCCESSFUL_SKILLS_JSON：安装成功的 skill 名称（JSON 数组）
• GSC_SKILLS_FAILED_SKILLS_JSON：安装失败的 skill 名称（JSON 数组）
• GSC_SKILLS_HOOK_CONTEXT_FILE：上下文 JSON 文件路径

Hook 脚本模板（示例）

import { cpSync, existsSync, mkdirSync } from 'node:fs';
import { join, resolve } from 'node:path';

function requiredEnv(name) {
	const value = process.env[name];
	if (!value) {
		throw new Error(`Missing required env: ${name}`);
	}
	return value;
}

const cloneDir = requiredEnv('GSC_SKILLS_CLONE_DIR');
const projectDir = process.cwd();

// 例：把仓库中的 extra-templates 目录复制到当前项目 .gsc-extra 下
const fromDir = resolve(cloneDir, 'extra-templates');
const toDir = resolve(projectDir, '.gsc-extra');

if (!existsSync(fromDir)) {
	console.log('[hook] skip: extra-templates not found');
	process.exit(0);
}

mkdirSync(toDir, { recursive: true });
cpSync(fromDir, join(toDir, 'extra-templates'), {
	recursive: true,
	force: true,
});

console.log('[hook] copied extra files successfully');

Hook 脚本模板（PowerShell，Windows）

$cloneDir = $env:GSC_SKILLS_CLONE_DIR
if ([string]::IsNullOrWhiteSpace($cloneDir)) {
	throw 'Missing required env: GSC_SKILLS_CLONE_DIR'
}

$projectDir = (Get-Location).Path

# 例：把仓库中的 extra-templates 目录复制到当前项目 .gsc-extra 下
$fromDir = Join-Path $cloneDir 'extra-templates'
$toRoot = Join-Path $projectDir '.gsc-extra'
$toDir = Join-Path $toRoot 'extra-templates'

if (-not (Test-Path $fromDir)) {
	Write-Host '[hook] skip: extra-templates not found'
	exit 0
}

New-Item -ItemType Directory -Force -Path $toRoot | Out-Null
Copy-Item -Path $fromDir -Destination $toDir -Recurse -Force

Write-Host '[hook] copied extra files successfully'

调用示例：

gsc-skills add <source> --post-install-hook ".\scripts\post-install.ps1"

常见坑排查（Windows）

1. 脚本无法执行（ExecutionPolicy）

如果提示脚本被系统策略阻止，可在当前进程临时放开执行策略后再运行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
gsc-skills add <source> --post-install-hook ".\scripts\post-install.ps1"

2. 路径包含空格

--post-install-hook 的值建议始终使用双引号包裹，避免路径被错误拆分：

gsc-skills add <source> --post-install-hook ".\scripts\post install.ps1"

3. 返回码与失败策略

• hook 返回 0：视为成功。
• hook 返回非 0：视为失败。
• 默认行为：仅告警，skill 安装结果保留。
• 严格模式：追加 --hook-strict 后，hook 失败会使命令返回失败。

gsc-skills add <source> --post-install-hook ".\scripts\post-install.ps1" --hook-strict

4. 临时 clone 目录生命周期

hook 在安装后、cleanup 前执行。请在 hook 内完成你需要的复制；命令结束后临时 clone 目录会被清理。

如果你在维护 agent 目录映射，请以以下代码为准：

• src/core/agents.ts
• src/core/installer.ts
• src/types.ts

常见问题

1) 提示 source host 不被支持

请确认 source 来自 Lenovo GitLab：gitlab.xpaas.lenovo.com。

本地开发验证

pnpm install
pnpm test:run
pnpm build
node bin/cli.mjs --version
node bin/cli.mjs --help