# Changelog

All notable changes to this skill are documented here.
Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: [SemVer](https://semver.org/)

## [0.2.0] - 2026-08-24

### Added

- add the shared feedback-classification and approval-invalidation gate used by every LovStudio Skill

## [0.1.2] - 2026-05-07

### Fixed

- make direct clone install path configurable
- replace fixed runtime install directory with SKILL_SKILLS_INSTALL_DIR

## [0.1.1] - 2026-05-07

### Fixed

- add release metadata
- add README version badge and changelog entry

# GitHub 协作管家 · GitHub Collaborator Manager

![Version](https://img.shields.io/badge/version-0.2.0-CC785C)

Grant, revoke, and audit collaborator access on **private** GitHub repos — by
GitHub username **or** email address — with read-only as the safe default.

Use when you want to share a private repo with a client or contractor
without making the repo public.

## Install

```bash
npx skills add skill-publisher/gh-access-skill --all -g
```

Or clone directly:

```bash
git clone https://example.com/skills/gh-access-skill \
          "${SKILL_SKILLS_INSTALL_DIR:?Set SKILL_SKILLS_INSTALL_DIR}/lov-gh-access"
```

## Prerequisites

- [`gh`](https://cli.github.com) CLI authenticated (`gh auth status`)
- Token scopes: `repo` (always), `admin:org` (for org-owned repos)
- You must be a repo admin (personal repo) or org owner / repo admin (org repo)

## What it does

```
                 ┌──────────────────────────────────────────────┐
  Client input:  │  alice                                       │
  "give these    │  bob@example.com                             │
  folks access"  │  carol@startup.io                            │
                 │  typo-user                                   │
                 └──────────────────┬───────────────────────────┘
                                    ▼
                    ┌───────────────────────────────┐
                    │  Resolve each identifier      │
                    │  • username → verify exists   │
                    │  • email → search by email    │
                    │           → org invite fallback│
                    └───────────────┬───────────────┘
                                    ▼
                ┌───────────────────────────────────────────┐
                │  Show resolution table, confirm           │
                └───────────────────┬───────────────────────┘
                                    ▼
                ┌───────────────────────────────────────────┐
                │  PUT /repos/{owner}/{repo}/collaborators  │
                │  (permission=pull by default)             │
                └───────────────────┬───────────────────────┘
                                    ▼
                          Invitation emails sent
```

## Subcommands

| Mode | What it does |
|---|---|
| **grant** | Invite one or more people as collaborators with a chosen permission. |
| **revoke** | Remove collaborators (idempotent — safe to re-run). |
| **list** | Show active collaborators + pending invitations for the repo. |

## Permission levels

| Level | Effect | When to use |
|---|---|---|
| `pull` *(default)* | Read code, clone, open/comment on issues and PRs | Clients, reviewers, most external access |
| `triage` | `pull` + manage issues/PRs (label, close) | Trusted external collaborators |
| `push` | Write to non-protected branches | Contractors actively contributing code |
| `maintain` | `push` + manage repo settings (except destructive) | Senior contractors |
| `admin` | Full control | Rare — requires explicit confirmation |

**The skill defaults to `pull` and requires an explicit request to escalate.**

## Usage examples

### Invite one client by email (org repo)

```
User: 把 acme/internal-dashboard 开给 client@acme.com，只读
→ Skill resolves client@acme.com:
    - If they have a GitHub account with that email → invite by username
    - If not → send org invite by email (pending until they create / link account)
→ Permission: pull
```

### Batch invite mixed list

```
User: 给这几个人开 skill-publisher/handoff-bundle 的权限:
      alice
      bob@startup.io
      carol-github

→ Skill resolves all three, shows a table, asks to confirm,
  then issues 3 PUT calls with permission=pull.
```

### List who has access

```
User: 谁现在能访问 skill-publisher/handoff-bundle?
→ Skill shows:
    Active:    alice (pull), carol-github (push)
    Pending:   bob@startup.io (pull, invited 2d ago)
```

### Revoke

```
User: 把 alice 从 skill-publisher/handoff-bundle 踢出去
→ Skill confirms, then DELETEs the collaborator.
```

## Resolution statuses

When processing a mixed list, each identifier ends up in one of these buckets:

| Status | Meaning | Action |
|---|---|---|
| `user_ok` | Username verified on GitHub | Invite directly |
| `email_to_user` | Email resolved to a public GitHub account | Invite that username |
| `email_invited` | Email had no public account, org invite sent | Recipient accepts via email |
| `email_no_account` | Email, no GitHub account, **personal repo** | Skip — ask user for username |
| `user_not_found` | Username doesn't exist (typo?) | Skip, report |

## Safety defaults

- Read-only (`pull`) unless explicitly overridden
- Always show a resolution table before writing
- Ask to confirm before batch revokes
- Escalation to `admin` / `maintain` requires explicit secondary confirmation
- Writes are sequential so partial failures are legible in the report

## License

MIT

---
name: lov-gh-access
category: Developer Tools
tagline: "Grant / revoke / list collaborator access on private GitHub repos by username or email."
description: >
  Open a private GitHub repo to external clients or contractors without making
  it public. Accepts a mixed list of GitHub usernames and/or email addresses,
  resolves each to a GitHub account (falling back to an email invitation when
  the user has no discoverable account yet), and invites them as collaborators
  with a chosen permission level (default: read-only, sufficient for pulling
  code and filing issues / PRs). Also supports revoking access and listing
  current collaborators. Use when the user says "给客户开权限", "share private
  repo", "invite collaborator", "邀请外部协作者", "grant repo access", "客户要看代码",
  "revoke access", "撤销访问", "list collaborators", or similar.
license: MIT
compatibility: >
  Requires gh CLI authenticated with a token that has `repo` + `admin:org` scope
  (for org-owned repos, the caller must be a repo admin or org owner).
metadata:
  author: contributors
  version: "0.2.0"
  tags: github collaborator access invite private-repo permissions
---

# GitHub 协作管家 · GitHub Collaborator Manager

Grant, revoke, and audit collaborator access on private GitHub repos — by
username **or** email, with read-only as the safe default.

## Prerequisites

- `gh` CLI authenticated (`gh auth status`) with a token that has:
  - `repo` scope (always)
  - `admin:org` scope (if the target repo is org-owned; caller must be org owner or repo admin)
- The target repo exists and is accessible to the caller.

## Subcommands

This skill has three modes. Pick based on the user's intent:

| User intent | Subcommand |
|---|---|
| "开权限 / share / invite / grant" | **grant** |
| "撤销 / remove / revoke / 踢出" | **revoke** |
| "谁有权限 / who has access / list" | **list** |

If intent is unclear, use `AskUserQuestion` to disambiguate.

## Workflow

### Step 0: Collect inputs via AskUserQuestion

**ALWAYS** collect the following BEFORE touching the API:

1. **Target repo** — `<owner>/<repo>` (e.g. `skill-publisher/private-demo`). If the
   user is inside a git repo, pre-fill from `gh repo view --json nameWithOwner -q .nameWithOwner`.
2. **Subcommand** — grant / revoke / list.
3. **(grant/revoke only) Identifiers** — a whitespace- or comma-separated list
   of GitHub usernames and/or email addresses. Mixed is fine.
4. **(grant only) Permission level** — default `pull` (read-only). Offer:
   - `pull` — read + issues + PRs (recommended default)
   - `triage` — read + can label/close issues & PRs, no code write
   - `push` — write access (⚠ confirm explicitly)
   - `maintain` / `admin` — block unless user explicitly insists

Never silently escalate. If the user just says "给他权限" without specifying
level, default to `pull` and state that clearly.

### Step 1: Resolve identifiers → GitHub usernames

For each identifier in the list, follow this resolution chain and record the
outcome per identifier (for the final summary report):

```
identifier → classify → resolve
```

**Classification rule:** an identifier containing `@` is treated as an email,
otherwise as a GitHub username.

#### Case A — looks like a username

1. Verify the account exists:
   ```bash
   gh api "users/<login>" --jq '.login' 2>/dev/null
   ```
2. If it returns the login → resolved as `login`, status `user_ok`.
3. If the call 404s → status `user_not_found`. Do NOT fall back to email invite
   (we don't have an email). Report and skip.

#### Case B — looks like an email

1. Search by email:
   ```bash
   gh api "search/users?q=<email>+in:email" --jq '.total_count, .items[0].login'
   ```
2. If `total_count >= 1` and a login is returned → resolved as `login`,
   status `email_to_user`.
3. If `total_count == 0` → fall back to **email invite** path:
   - For org repos: `gh api -X POST "orgs/<org>/invitations" -f email=<email> -f role=direct_member` then add the pending member as an outside collaborator on the repo once they accept. **Note**: inviting directly-to-repo by email is not supported by the REST API for non-org personal repos — if the target is a personal repo, report `email_no_account` and ask the user to obtain the recipient's GitHub username.
   - Status: `email_invited` (org) or `email_no_account` (personal repo).

Show the resolution table to the user **before** performing writes:

| Input | Type | Resolved | Status |
|---|---|---|---|
| `alice` | username | `alice` | user_ok |
| `bob@example.com` | email | `bobhub` | email_to_user |
| `carol@startup.io` | email | — | email_invited (or email_no_account) |
| `typo-user` | username | — | user_not_found |

Ask the user to confirm before proceeding with writes. Skip `user_not_found`
and `email_no_account` entries by default.

### Step 2: Execute

#### grant

For each resolved username, issue a repo invitation:

```bash
gh api -X PUT "repos/<owner>/<repo>/collaborators/<login>" \
       -f permission=<pull|triage|push|maintain|admin>
```

- Response `201` = invitation sent (pending until recipient accepts).
- Response `204` = already a collaborator; permission was updated.
- Response `422` = user not found or already pending; inspect and report.

For org-repo email invites that resolved to `email_invited` above, no
additional call is needed — the org invitation covers repo access once the
user accepts. Tell the user to remind the recipient to check their email.

#### revoke

```bash
gh api -X DELETE "repos/<owner>/<repo>/collaborators/<login>"
```

- Response `204` = removed (or was never a collaborator — idempotent).
- For email-only identifiers with no resolved login: use
  `gh api -X DELETE "orgs/<org>/memberships/<login>"` only if the user
  explicitly wants to remove from the whole org; otherwise skip and report.

Before executing revokes, **show the list of logins that will be removed and
ask for a final confirmation** (revokes are visible to the recipient and can
be socially awkward to reverse).

#### list

```bash
gh api "repos/<owner>/<repo>/collaborators?affiliation=all" \
       --jq '.[] | {login, permissions}' \
       --paginate
```

Also list pending invitations:

```bash
gh api "repos/<owner>/<repo>/invitations" --paginate \
       --jq '.[] | {invitee: .invitee.login, email, permissions, created_at}'
```

Present as two tables: **Active collaborators** and **Pending invitations**.

### Step 3: Report

Show a final summary table for grant/revoke operations:

```
gh-access report — <owner>/<repo>
=================================
Granted (pull): alice, bobhub
Invited via email: carol@startup.io (pending org invite)
Skipped: typo-user (user_not_found)
```

Include the invitation URL the user can share manually if helpful:
`https://github.com/<owner>/<repo>/invitations`

## Rules

- **Default to `pull` (read-only)** unless the user explicitly names a higher
  permission. State the chosen level clearly before executing.
- **Never escalate to `admin`/`maintain`** without an explicit, unambiguous
  request — ask a confirming `AskUserQuestion` even if the user seemed to ask.
- **Show the resolution table before writes.** Clients mistyping a username is
  common; showing the resolved login prevents inviting the wrong person.
- **Idempotent revokes.** A `204` on a non-collaborator is fine — don't panic.
- **Batch-friendly.** A single invocation can process a long mixed list;
  execute resolution in parallel where possible, but keep writes sequential so
  partial failures are easy to report.
- **Email invites only work cleanly for org repos.** For personal repos
  without a resolved username, stop and ask the user to obtain a GitHub
  username from the recipient.
- **Private repos only are the typical case**, but this skill works on public
  repos too — no need to refuse.

## Common gh CLI quick reference

```bash
# Who am I? What scopes do I have?
gh auth status

# Is this a repo I can admin?
gh api "repos/<owner>/<repo>" --jq '.permissions'

# Cancel a pending invitation
gh api -X DELETE "repos/<owner>/<repo>/invitations/<invitation_id>"

# Show org membership of a user
gh api "orgs/<org>/memberships/<login>" --jq '.role, .state'
```

## Runtime context (shared)

运行前读取本 Skill 包的 `skill.yaml`，由宿主提供 `skill-runtime/v1` 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。

- 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。
- `required: true` 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。
- 报错提供可复制的 `context_id`、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。

## 通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 `task-specific`（仅本次）还是 `reusable`（可跨任务复用）。
2. `task-specific` 只修改当前任务，不改 Skill。
3. `reusable` 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. `reusable` 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。

schema: skill-manifest/v1
id: lov-gh-access
version: "0.2.0"
runtime: skill-runtime/v1
context:
  profile:
    fields:
    - path: identity.name
      required: true
      question: 如果本次输出需要品牌身份，请提供品牌名称。
    - path: identity.logo
      required: false
      question: 如果需要使用品牌 Logo，请提供 Logo 地址或文件路径。
    - path: brand.tone
      required: false
      question: 如果已有品牌语气或审美关键词，请提供它们。
  preferences:
    namespace: lov_gh_access
    fields:
    - path: user.language
      required: false
      question: 希望使用哪种语言输出？
    - path: user.timezone
      required: false
      question: 需要使用哪个时区处理日期和时间？
  interaction:
    ask_missing: true
    max_questions: 1