gitlink-cli/skills

GitLink CLI Skills 指南

欢迎使用 GitLink CLI Skills！本指南帮助你快速上手和充分利用 gitlink-cli 的所有功能。

📚 Skills 是什么？

Skills 是为 Claude Code 和其他 AI 代理设计的结构化知识库，包含：

• SKILL.md — 命令参考和使用指南
• REFERENCE.md — API 详细参考和参数说明
• TROUBLESHOOTING.md — 常见问题和解决方案
• examples/ — 真实工作流示例

AI 代理通过 Skills 可以自动化操作 GitLink 平台，无需手动查阅文档。

---

🚀 快速开始

1. 安装和认证

# 首次使用：登录
gitlink-cli auth login

# 验证登录状态
gitlink-cli auth status

# 查看当前用户
gitlink-cli user +me

详见: gitlink-shared/examples/auth-workflow.md

2. 查看可用命令

# 列出所有 Shortcuts
gitlink-cli --help

# 查看特定命令帮助
gitlink-cli repo --help
gitlink-cli issue --help
gitlink-cli pr --help

3. 使用 JSON 格式便于脚本处理

# 所有命令都支持 --format json
gitlink-cli user +me --format json
gitlink-cli repo +list --format json
gitlink-cli issue +list --format json

---

📁 Skills 目录结构

skills/
├── README.md                          # 本文件
├── gitlink-shared/                    # 共享基础规则
│   ├── SKILL.md                       # 认证、全局参数、安全规则、分支约定
│   ├── REFERENCE.md                   # API 详细参考、错误处理
│   ├── TROUBLESHOOTING.md             # 常见问题排查
│   └── examples/
│       └── auth-workflow.md           # 认证工作流示例
├── gitlink-repo/                      # 仓库管理
│   ├── SKILL.md                       # 仓库操作指南
│   ├── REFERENCE.md                   # 仓库 API 参考
│   └── examples/
│       └── repo-workflow.md           # 仓库管理工作流
├── gitlink-issue/                     # Issue 管理
│   ├── SKILL.md                       # Issue 操作指南
│   ├── REFERENCE.md                   # Issue API 参考
│   └── examples/
│       └── issue-workflow.md          # Issue 全流程工作流
├── gitlink-pr/                        # Pull Request
│   ├── SKILL.md                       # PR 操作指南
│   ├── REFERENCE.md                   # PR API 参考
│   └── examples/
│       └── pr-workflow.md             # PR 工作流
├── gitlink-member/                    # 仓库成员管理
│   └── SKILL.md                       # 成员与邀请链接操作指南
├── gitlink-branch/                    # 分支管理
│   ├── SKILL.md                       # 分支操作指南
│   └── examples/
│       └── branch-workflow.md         # 分支工作流
├── gitlink-release/                   # 版本发布
│   ├── SKILL.md                       # Release 操作指南
│   ├── REFERENCE.md                   # Release API 参考
│   └── examples/
│       └── release-workflow.md        # Release 工作流
├── gitlink-search/                    # 搜索功能
│   ├── SKILL.md                       # 搜索操作指南
│   └── examples/
│       └── search-workflow.md         # 搜索工作流
├── gitlink-user/                      # 用户管理
│   └── SKILL.md                       # 用户操作指南
├── gitlink-org/                       # 组织管理
│   ├── SKILL.md                       # 组织操作指南
│   └── examples/
│       └── org-workflow.md            # 组织工作流
├── gitlink-ci/                        # CI/CD
│   ├── SKILL.md                       # CI 操作指南
│   └── examples/
│       └── ci-workflow.md             # CI 工作流
├── gitlink-pipeline/                  # 流水线工作流
│   └── SKILL.md                       # Pipeline 操作指南
├── gitlink-pm/                        # 项目管理
│   └── SKILL.md                       # PM 操作指南
├── gitlink-health/                    # 项目健康度分析
│   ├── SKILL.md                       # 健康度分析指南
│   ├── data/
│   │   ├── .gitignore                 # 忽略 *.db 文件
│   │   └── .gitkeep                   # 占位文件
│   ├── references/
│   │   └── queries.md                 # SQL 查询参考
│   └── asset/
│       └── health_report_template.md  # 报告模板
└── gitlink-workflow/                  # AI 自动化工作流
    └── SKILL.md                       # 工作流模板（Issue 分类、PR Review、Release Notes）

---

📖 所有 Skills 概览

核心 Skills

Skill	说明	常用命令
gitlink-shared	认证、全局参数、API 参考、安全规则、分支约定	auth login, auth status
gitlink-repo	仓库管理与洞察	repo +list, repo +info, repo +languages, repo +contributors, repo +code-stats, repo +follow, repo +like
gitlink-issue	Issue 管理	issue +create, issue +list, issue +view, issue +close, issue +batch-close
gitlink-pr	Pull Request	pr +list, pr +create, pr +view, pr +merge, pr +reviews, pr +review
gitlink-branch	分支管理	branch +list, branch +create, branch +delete, branch +protect
gitlink-release	版本发布	release +list, release +create, release +edit, release +update, release +view
gitlink-milestone	里程碑管理	milestone +list, milestone +create, milestone +view, milestone +close
gitlink-label	标签管理	label +list, label +create, label +delete
gitlink-file	仓库文件操作	file +browse, file +get, file +create, file +update, file +delete
gitlink-webhook	Webhook 管理	webhook +list, webhook +create, webhook +delete
gitlink-member	项目成员管理	member +list, member +add, member +remove

辅助 Skills

Skill	说明	常用命令
gitlink-search	搜索功能	search +repos, search +users
gitlink-user	用户管理	user +me, user +info
gitlink-org	组织管理	org +list, org +info, org +members
gitlink-ci	CI/CD	ci +builds, ci +logs
gitlink-pipeline	流水线工作流	pipeline +runs, pipeline +run, pipeline +logs
gitlink-pm	项目管理	通过 Raw API 访问
gitlink-workflow	AI 工作流	Issue 分类、PR Review、Release Notes
gitlink-health	开源项目健康度	详情见SKILL.md
gitlink-snippet	本地代码片段管理	snippet +create, snippet +search, snippet +list

智能化与工作流 Skills（AI 编排，串联多步）

Skill	说明	常用命令 / 能力
gitlink-onboarding	新人引导	搜 good-first-issue、5 维度友好度评估、生成引导评论
gitlink-digest	项目简报	跨源聚合 Issue/PR/CI/通知成日报
gitlink-todo	我的待办	汇总 @我 / 分配我 / 待 review，按紧急度排序
gitlink-pr-guard	代码质量看门人	PR→Review→CI→质量判定→合并（端到端门禁）

以上 5 个为本次新增的 AI 工作流 Skill，均兼容 Claude Code 等 Agent，详见各 SKILL.md。

---

🎯 使用场景

场景 1：查看仓库信息

# 在仓库目录下自动解析 owner/repo
cd ~/my-project
gitlink-cli repo +info

# 或显式指定
gitlink-cli repo +info --owner wbtiger --repo gitlink-cli

详见: gitlink-repo/examples/repo-workflow.md

场景 2：创建和管理 Issue

# 创建 Issue
gitlink-cli issue +create -t "Bug: 登录失败" -b "复现步骤..."

# 查看 Issue
gitlink-cli issue +view -i 123

# 添加评论
gitlink-cli issue +comment -i 123 -b "已修复"

# 关闭 Issue
gitlink-cli issue +close -i 123

# 预览批量关闭 Issue
gitlink-cli issue +batch-close --numbers 123,124 --dry-run

详见: gitlink-issue/examples/issue-workflow.md

场景 3：管理分支和发布

# 创建分支
gitlink-cli branch +create -n develop

# 保护分支
gitlink-cli branch +protect -n master

# 创建 Release
gitlink-cli release +create -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."

# 查看 Release
gitlink-cli release +view -i <version_id>

详见: gitlink-release/examples/release-workflow.md

场景 4：搜索和发现

# 搜索仓库
gitlink-cli search +repos -k "machine learning"

# 搜索用户
gitlink-cli search +users -k "zhangsan"

# 查看组织
gitlink-cli org +list
gitlink-cli org +info -i Gitlink

详见: gitlink-search/examples/search-workflow.md

---

📚 文档导航

快速查找

• 我想了解认证: gitlink-shared/SKILL.md
• 我想查看 API 细节: gitlink-shared/REFERENCE.md
• 我遇到了错误: gitlink-shared/TROUBLESHOOTING.md
• 我想看工作流示例: 查看各 Skill 下的 examples/ 目录

按功能分类

仓库操作:

• gitlink-repo/SKILL.md - 仓库命令
• gitlink-branch/SKILL.md - 分支命令
• gitlink-repo/examples/repo-workflow.md - 完整工作流

Issue 和 PR:

• gitlink-issue/SKILL.md - Issue 命令
• gitlink-pr/SKILL.md - PR 命令
• gitlink-issue/examples/issue-workflow.md - Issue 工作流

发布和搜索:

• gitlink-release/SKILL.md - Release 命令
• gitlink-pipeline/SKILL.md - Pipeline 命令
• gitlink-search/SKILL.md - 搜索命令

组织和用户:

• gitlink-org/SKILL.md - 组织命令
• gitlink-user/SKILL.md - 用户命令

---

❓ 常见问题

Q: 如何在脚本中使用 gitlink-cli？

A: 使用 --format json 获取结构化输出：

gitlink-cli repo +list --format json | jq '.data.projects[] | .name'

Q: 如何自动解析 owner/repo？

A: 在 git 仓库目录下运行命令，CLI 会自动从 git remote origin 解析：

cd ~/my-project
gitlink-cli repo +info  # 自动使用当前仓库

Q: Token 过期了怎么办？

A: 重新登录：

gitlink-cli auth login

Q: 如何查看完整的 API 参考？

A: 查看 gitlink-shared/REFERENCE.md

Q: 遇到错误怎么办？

A: 查看 gitlink-shared/TROUBLESHOOTING.md

---

🤖 AI Agent 使用

Claude Code 和其他 AI 代理可以直接使用这些 Skills 自动化操作 GitLink 平台：

用户: "帮我在 GitLink 上创建一个 Issue"
↓
AI 代理读取 gitlink-issue/SKILL.md
↓
AI 代理执行: gitlink-cli issue +create -t "..." -b "..."
↓
完成！

AI 代理可以：

• ✅ 自动创建和管理 Issue
• ✅ 自动创建和合并 PR
• ✅ 自动发布 Release
• ✅ 自动分类 Issue
• ✅ 自动生成 Release Notes
• ✅ 自动执行代码审查

---

📊 测试状态

✅ 生产就绪 (8.5/10)

• 8/8 常用场景通过
• 所有边界情况处理正确
• 完整的文档和示例

详见: ../doc/SKILLS_TEST_REPORT_2026-04-02.md

---

🔗 相关资源

• 主项目 README - gitlink-cli 项目说明
• 设计文档 - 架构设计和开发计划
• 测试报告 - 功能测试报告
• 代码同步方案 - GitHub ↔ GitLink 同步设计
• gitlink-bisync - 代码双向同步系统

---

📞 获取帮助

• 命令帮助: gitlink-cli <command> --help
• 故障排查: gitlink-shared/TROUBLESHOOTING.md
• API 参考: gitlink-shared/REFERENCE.md
• 工作流示例: 查看各 Skill 下的 examples/ 目录

---

🎓 下一步

1. 阅读 gitlink-shared/SKILL.md 了解基础
2. 查看 gitlink-shared/examples/auth-workflow.md 完成认证
3. 根据需求选择相应的 Skill 文档
4. 参考 examples/ 目录中的工作流示例
5. 使用 AI 代理自动化你的工作流

祝你使用愉快！🚀