git-repo-beginner-guide

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Git 仓库新手引导

## Overview

帮助非技术用户安全、低焦虑地使用 Git 仓库协作。默认由 AI 代做可执行操作，并把必要概念翻译成用户能理解的决策点。

## 核心原则

- 先问目标，不先教术语。用户通常要的是“保存一版”“发给团队”“拿到项目”“回到昨天”，不是学习 Git。
- 先保护现场。任何会丢弃、覆盖、重写历史、删除远程内容的动作，都先解释影响并确认。
- 默认代办。能由 AI 检查、执行、验证的，不要让用户自己照抄命令；用户只负责授权、选择平台、确认风险。
- 渐进解释。只有当概念会影响用户决策时才解释，例如远程仓库、提交、同步、冲突。分支、rebase、stash 等先不主动引入。
- 平台中立。不要默认 GitHub；先识别或询问 GitHub、GitLab、Gitee、Bitbucket、自建 Git、公司内网平台等。
- 用生活化比喻，但保留必要名词。第一次出现可写“提交 commit：给当前文件拍一张可回退的快照”。
- 先小步闭环。每次只完成一个可验证状态：已登录、已连接远程、已保存本地版本、已同步到远程、已恢复文件。

## 交互流程

### 1. 先识别用户处境

先用自然语言复述用户目标，然后做最少量澄清。

常见处境：

- “我有一个本地文件夹，想放到代码平台上” → 初始化/连接远程/首次同步
- “别人给我一个链接，我要拿下来” → 克隆/权限/打开项目
- “我改完了，想保存并发给别人” → 查看改动/提交/推送
- “我怕改坏，想留个版本” → 本地提交或备份分支，按复杂度选择
- “提示要登录/没有权限” → 平台授权引导
- “提示冲突/推不上去” → 解释有人也改了同一处，先保护本地改动再合并
- “我要回到之前” → 明确是恢复文件、撤销未提交改动、还是回到某个历史版本

如果上下文已经足够，不要继续追问。直接说“我先帮你检查当前状态”。

### 2. 明确 AI 能帮什么

在开始前用一句话降低用户负担：

> 我可以帮你检查当前文件状态、创建版本记录、连接远程仓库、同步到平台；你只需要在需要网页登录授权时确认账号，或者告诉我目标仓库链接。

避免说“你运行以下命令”。除非当前环境无法代办，才给用户步骤。

### 3. 检查当前状态并翻译结果

检查本地是否是仓库、是否有远程地址、当前有无未保存改动、是否已登录相关平台。回复用户时不要直接堆 `git status` 原文，先给可行动摘要：

- “这个文件夹还不是仓库，我可以把它变成一个可记录版本的文件夹。”
- “它已经连接到远程平台，地址是 X。”
- “现在有 6 个文件改动了，还没有保存成版本。”
- “远程平台需要登录授权，接下来会打开/提供平台自己的登录流程。”

需要展示命令输出时，只摘关键含义。

### 4. 授权引导要平台灵活

先识别远程 URL 或用户指定平台，再选择授权方式：

- GitHub：优先 `gh auth status` / `gh auth login`；必要时解释浏览器 OAuth、SSH、token 的差异。
- GitLab：优先平台 CLI 或 HTTPS token/SSH；自建 GitLab 注意域名和公司 SSO。
- Gitee：常见为 HTTPS 凭证、私人令牌或 SSH key；不要套用 GitHub 文案。
- Bitbucket：注意 workspace、app password、SSH。
- 自建平台：先问/识别平台地址，按 HTTPS token、SSH key、公司 SSO 三类引导。

授权沟通规范：

- 不要求用户把密码、token、私钥粘贴到聊天里。
- 需要 token 时，引导用户在平台页面生成，并说明只保存到系统凭据/CLI，不在聊天中泄露。
- 需要 SSH key 时，先检查是否已有可用 key；没有再创建，并指导用户把公钥加到平台。
- 遇到 SSO/组织权限时，告诉用户“这是账号权限问题，不是你的文件坏了”。

## 复杂度控制

### 不主动引入分支

如果用户只想把个人文件夹放到远程、保存一版、拉取项目或同步改动，不主动讲分支。

只有在以下情况才引入分支：

- 用户明确要多人协作或不想影响主版本
- 当前仓库已有分支策略或保护规则
- 需要在不动主线的情况下尝试修改
- 提交到主分支被拒绝，需要通过 PR/MR

第一次解释分支时保持短句：

> 分支可以理解成一份独立草稿。你可以在草稿里改，确认没问题后再合到正式版本。

不要一开始讲 rebase、cherry-pick、worktree、detached HEAD。

### 冲突处理面向结果

冲突不是“报错”，而是“同一处内容有两份修改，系统不知道该选哪份”。

处理前先说明：

- 你的本地改动还在
- 远程也有别人/另一台设备的改动
- 我会先帮你看冲突位置，再让你决定保留哪部分或合并两边

如果用户不懂代码，优先生成“冲突内容对照摘要”，不要让用户读冲突标记。

### 版本恢复先问恢复粒度

用户说“还原/回退/恢复”时，先判断是哪一种：

- 只撤销还没保存成版本的本地修改
- 找回某个被删文件
- 查看之前某个版本
- 把整个项目回到某个历史版本
- 远程也要同步回退

远程回退、强推、删除历史前必须明确风险并取得确认。对非技术用户可说：

> 这会改变团队平台上看到的历史版本，可能影响别人。我先给你一个不改远程历史的恢复方案。

## 推荐话术

### 初始化/首次同步

From lintendo/Axhub-Skills, MIT.

More from lintendo/Axhub-Skills