diff --git a/skills/gitlink-onboard/SKILL.md b/skills/gitlink-onboard/SKILL.md
new file mode 100644
index 0000000..c9feee9
--- /dev/null
+++ b/skills/gitlink-onboard/SKILL.md
@@ -0,0 +1,81 @@
+---
+name: gitlink-onboard
+version: 1.0.0
+description: "新贡献者上手指南：一站式生成项目简介、技术栈、核心目录导航、社区文件检查、good-first-issue、核心贡献者联系与上手步骤，帮助新人快速参与项目。当用户提到「上手指南」「怎么参与这个项目」「新人指南」「onboarding」「接手项目」「从哪开始贡献」时触发。"
+metadata:
+  requires:
+    bins: ["gitlink-cli"]
+    optional_bins: ["python"]
+  cliHelp: "gitlink-cli repo --help"
+---
+
+# gitlink-onboard（新贡献者上手指南生成器）
+
+**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
+**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
+**CRITICAL — 本技能全程只读，不修改任何远程数据。**
+
+> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。
+
+## 何时使用本技能
+
+- 新人想参与一个项目，需要一份完整的上手指南
+- 用户问「这个项目怎么参与 / 从哪开始 / 代码在哪 / 找谁问」
+- 接手一个陌生仓库前先了解全貌
+
+## 与 gitlink-newcomer 的区别
+
+`gitlink-newcomer` 聚焦「识别 good-first-issue 并生成引导评论」（面向维护者整理任务）；
+本技能输出的是**面向新人的完整上手指南**：项目是什么、技术栈、代码在哪、社区文件、
+从哪个 Issue 开始、找谁问、怎么提 PR——一站式覆盖。
+
+## 能力概览
+
+| 能力 | 说明 |
+|------|------|
+| 项目概览 | 简介、社区指标、默认分支 |
+| 技术栈识别 | 从依赖文件推断（go.mod/package.json…） |
+| 核心目录导航 | 列出目录并标注语义（cmd/src/internal…） |
+| 社区文件检查 | README/CONTRIBUTING/行为准则是否齐全 |
+| good-first-issue | 适合新手上手的 Issue |
+| 核心贡献者 | 遇到问题找谁 |
+| 上手步骤 | 标准 Fork → 改 → PR 流程 |
+
+## 工作流：生成上手指南
+
+### 方式 A：配套脚本（推荐）
+
+```bash
+python scripts/onboard.py --owner Gitlink --repo gitlink-cli
+python scripts/onboard.py --owner Gitlink --repo gitlink-cli --format json
+```
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `--owner` / `--repo` | string | 是* | 仓库（*或用 `--slug`） |
+| `--slug` | string | 否 | `owner/repo` 或完整 URL |
+| `--format` | string | 否 | `markdown`（默认）或 `json` |
+| `--output` | string | 否 | 输出文件 |
+
+### 方式 B：用 gitlink-cli 命令
+
+```bash
+gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
+gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=&ref=master' --format json
+gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json
+gitlink-cli api GET /:owner/:repo/contributors --format json
+```
+
+## API 注意事项
+
+- 技术栈依据根目录依赖文件推断；核心目录导航依据 `sub_entries` 返回的目录。
+- good-first-issue 用关键词启发式识别（typo/docs/test/翻译 等）。
+- 数据采集全程只读。
+
+## References
+
+- [api-reference.md](references/api-reference.md) — 采集接口与字段
+- [guide-structure.md](references/guide-structure.md) — 上手指南结构与识别规则
+- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则
diff --git a/skills/gitlink-onboard/references/api-reference.md b/skills/gitlink-onboard/references/api-reference.md
new file mode 100644
index 0000000..e039003
--- /dev/null
+++ b/skills/gitlink-onboard/references/api-reference.md
@@ -0,0 +1,38 @@
+# gitlink-onboard API 参考
+
+> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。
+
+本技能全程只读。
+
+## 采集的接口
+
+| 接口 | 用途 |
+|------|------|
+| `GET /:owner/:repo.json` | 项目简介、默认分支、Star/Fork |
+| `GET /:owner/:repo/sub_entries.json?filepath=&ref=<branch>` | 根目录条目（技术栈识别 + 目录导航） |
+| `GET /:owner/:repo/issues.json` | 识别 good-first-issue |
+| `GET /:owner/:repo/contributors.json` | 核心贡献者 |
+
+## 使用的字段
+
+- 仓库：`description` / `default_branch` / `praises_count` / `forked_count`
+- 目录条目：`name` / `type`(file|dir)
+- Issue：`name`/`subject` / `description` / `issue_status`
+- 贡献者：`login`/`name` / `contributions`
+
+## 输出字段（JSON）
+
+```json
+{
+  "owner","repo","description","default_branch","stars","forks",
+  "stacks": ["Go","Make"],
+  "navigation": [{"name":"cmd","hint":"命令行入口"}],
+  "good_first": [{"id","title"}],
+  "health": {"README":true,"CONTRIBUTING":false,"行为准则":false},
+  "core_contributors": [{"name","contributions"}]
+}
+```
+
+## 错误处理
+
+目录采集失败时降级为空导航，不中断其他部分。沿用 gitlink-shared 错误码。
diff --git a/skills/gitlink-onboard/references/guide-structure.md b/skills/gitlink-onboard/references/guide-structure.md
new file mode 100644
index 0000000..d375c19
--- /dev/null
+++ b/skills/gitlink-onboard/references/guide-structure.md
@@ -0,0 +1,46 @@
+# 上手指南结构与识别规则
+
+## 指南六段结构
+
+1. **项目是什么**：简介 + 技术栈 + 社区指标
+2. **代码在哪**：核心目录导航
+3. **社区文件是否齐全**：README/CONTRIBUTING/行为准则
+4. **从哪个 Issue 开始**：good-first-issue
+5. **遇到问题找谁**：核心贡献者
+6. **上手步骤**：Fork → 改 → PR
+
+## 技术栈识别
+
+依据根目录依赖/配置文件推断：
+
+| 文件 | 技术栈 |
+|------|--------|
+| go.mod | Go |
+| package.json | Node.js / JavaScript |
+| requirements.txt / pyproject.toml | Python |
+| Cargo.toml | Rust |
+| pom.xml / build.gradle | Java |
+| composer.json | PHP |
+| Gemfile | Ruby |
+| Dockerfile | Docker |
+| Makefile | Make |
+
+## 核心目录语义提示
+
+| 目录 | 含义 |
+|------|------|
+| src / lib | 源码 / 库 |
+| cmd | 命令行入口 |
+| internal / pkg | 内部包 / 公共包 |
+| app / core | 应用 / 核心模块 |
+| docs | 文档 |
+| test(s) | 测试 |
+| examples | 示例 |
+| skills | Agent Skills |
+
+带语义提示的目录优先展示，帮助新人快速定位代码入口。
+
+## good-first-issue 识别
+
+开放 Issue 中，标题/正文含 typo/docs/readme/test/翻译/示例 等关键词且描述较短（<800 字）
+的，判定为新手友好，最多取 8 个。