diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..1014ba7
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..f47922c
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.zip binary
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..7fc6446
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Questions and workflow discussions
+ url: https://github.com/hyt315/github-oss-ops/discussions
+ about: Ask usage questions or discuss workflow design here.
+ - name: Report a security vulnerability privately
+ url: https://github.com/hyt315/github-oss-ops/security/advisories/new
+ about: Do not disclose credentials or vulnerability details in a public issue.
diff --git a/.github/repository-metadata.yml b/.github/repository-metadata.yml
new file mode 100644
index 0000000..c77571b
--- /dev/null
+++ b/.github/repository-metadata.yml
@@ -0,0 +1,26 @@
+repository: hyt315/github-oss-ops
+description: Approval-gated Agent Skill for GitHub Issue triage, PR review assistance, releases and repository health reporting.
+topics:
+ - agent-skills
+ - github
+ - github-actions
+ - issue-triage
+ - maintainer-tools
+ - open-source
+ - pull-request-review
+ - release-automation
+ - repository-management
+ - workflow-automation
+features:
+ issues: true
+ discussions: true
+ private-vulnerability-reporting: true
+ruleset:
+ target: main
+ require-pull-request: true
+ require-status-check: validate
+ block-force-push: true
+ block-deletion: true
+release:
+ tag: v1.1.0
+ title: GitHub OSS Ops v1.1.0
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..b03ffd2
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,20 @@
+name: Validate
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+ with:
+ node-version: "20"
+ - name: Validate skill package
+ run: node scripts/validate-skill.mjs
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..cf3a300
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to GitHub OSS Ops are documented here.
+
+## [1.1.0] - 2026-07-18
+
+### Added
+
+- Three end-to-end examples with explicit read/write approval boundaries.
+- Cross-platform static validator and GitHub Actions validation workflow.
+- Agent metadata, repository metadata, contributor attribution and a social-preview asset.
+
+### Changed
+
+- Corrected Codex installation to the current `~/.agents/skills` location and clarified ChatGPT/Codex naming.
+- Reworked authentication around public read-only access, official GitHub OAuth/MCP, authenticated GitHub CLI and least-privilege fine-grained PATs.
+- Rewrote the project landing page around outcomes, examples, downloads and a five-minute first run.
+
+### Security
+
+- Removed credential discovery that searched user directories or printed extracted tokens.
+- Prohibited asking users to paste credentials into chat or persisting credentials in the skill directory.
+- Replaced public vulnerability reporting with GitHub Private Vulnerability Reporting.
+
+## [1.0.2] - 2026-07-18
+
+- Aligned MCP tool names with the then-current consolidated GitHub MCP tools.
+
+## [1.0.1] - 2026-07-18
+
+- Replaced non-functional HTML anchors with Markdown headings.
+
+## [1.0.0] - 2026-07-18
+
+- Initial public release.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1df7903..d74e459 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,8 +15,9 @@
1. **Fork** 本仓库
2. **创建分支**：`git checkout -b feature/你的功能名`
3. **提交改动**：使用 Conventional Commits 格式（`feat:` / `fix:` / `docs:` 等）
-4. **推送分支**：`git push origin feature/你的功能名`
-5. **提交 Pull Request**：填写 PR 模板，说明改动内容和原因
+4. **运行验证**：`node scripts/validate-skill.mjs`
+5. **推送分支**：`git push origin feature/你的功能名`
+6. **提交 Pull Request**：填写 PR 模板，说明改动内容和原因
### 贡献 Skill 逻辑
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
new file mode 100644
index 0000000..9dd30cd
--- /dev/null
+++ b/CONTRIBUTORS.md
@@ -0,0 +1,4 @@
+# Contributors
+
+- [hyt315](https://github.com/hyt315) — creator, product direction and release ownership.
+- [ChatGPT (Codex)](https://github.com/codex) — security review, workflow design, validation, documentation and open-source release engineering.
diff --git a/README.md b/README.md
index 164a55f..408b82a 100644
--- a/README.md
+++ b/README.md
@@ -1,201 +1,148 @@
-# 🛠️ GitHub 开源项目运营 / GitHub OSS Ops
+# GitHub OSS Ops
-
+[中文](#中文) · [English](#english)
-**开源发布后的"AI 客服"：Issue 智能分流、PR 辅助审查、版本管理、运营报告，一站式搞定**
+[](https://github.com/hyt315/github-oss-ops/actions/workflows/validate.yml)
+[](https://github.com/hyt315/github-oss-ops/releases/latest)
+[](https://github.com/hyt315/github-oss-ops/releases)
+[](CONTRIBUTORS.md)
+[](LICENSE)
-**AI-powered operations for open-source repos: smart Issue triage, PR review assistance, release management, and ops reporting**
+给独立维护者和小团队使用的 GitHub 运营 Agent Skill：扫描 Issue/PR、生成可审查草稿、辅助版本发布，并把所有外部写操作留在明确批准之后。
-[](LICENSE)
-[]()
-[](SKILL.md)
-
-[English](#english) | [中文](#中文)
+```bash
+git clone https://github.com/hyt315/github-oss-ops.git ~/.agents/skills/github-oss-ops
+```
-
+[安装为 Agent Skill](#安装为-agent-skill) · [查看三个真实工作流](examples/README.md) · [下载最新版](https://github.com/hyt315/github-oss-ops/releases/latest)
----
+
## 中文
-## 📖 这是什么？
-
-**GitHub 开源项目运营** 是一个 AI Agent Skill，专为已发布的开源项目日常维护设计。它能自动扫描 Issue/PR、智能分类打标签、起草回复、审查代码、管理 Release 版本、处理过期 Issue，甚至生成运营报告。
-
-> 💡 与 [github-oss-prep](https://github.com/hyt315/github-oss-prep) 配合使用：oss-prep 负责项目发布准备，本技能负责发布后的日常运营。
-
-### ✨ 核心功能
-
-| 功能模块 | 说明 |
-|----------|------|
-| 🔍 **Issue 扫描** | 扫描未读 Issue，按类型智能分类（Bug/Feature/Question/文档） |
-| ✍️ **智能回复** | 基于模板自动起草回复，支持流转状态、打标签 |
-| 📋 **PR 审查** | 按规则审查 PR 标题格式、改动影响、敏感信息、工作流对齐 |
-| 📦 **版本管理** | 自动生成 Release Notes，基于 Conventional Commits 计算版本号 |
-| 🧹 **过期清理** | 扫描过期 Issue/PR，起草关闭或提醒回复 |
-| 📊 **运营报告** | 生成统计报告：新建/关闭趋势、响应时间、活跃贡献者排行 |
-| ⚙️ **自动化配置** | 生成 GitHub Actions 工作流，配置 Issue 自动管理 |
+### 它解决什么问题
----
+项目发布只是开始。维护者还要反复查看 Issue、确认重复问题、审查 PR、跟踪 CI、整理版本说明和处理长期无响应内容。GitHub OSS Ops 把这些步骤组织成可复核的工作流，同时保留人的最终决定权。
-## 🚀 快速开始
+| 工作流 | Skill 会做什么 | 默认边界 |
+| --- | --- | --- |
+| Issue 分流 | 聚合新 Issue、判断类型/优先级/重复项、起草回复 | 读取可直接进行；评论、标签和关闭需批准 |
+| PR 辅助审查 | 汇总 diff、CI、风险、测试和发布影响 | 不伪装成人工审查，不在未批准时提交 Review |
+| Release 管理 | 根据已合并改动建议 SemVer、生成说明、核对版本一致性 | Tag、Release 和推送分别确认 |
+| Stale 管理 | 识别长期无响应内容并提出分批处理建议 | 不自动批量关闭 |
+| 运营报告 | 输出响应时间、积压、合并和版本节奏 | 区分事实、推断与建议 |
-这是一个 AI Agent Skill，安装到任意 AI 编程助手后即可使用。
+### 三个可复核示例
-### 怎么用
+仓库包含三个完整示例，展示输入、只读分析、批准点与预期输出：
-安装后直接告诉 AI 助手你的需求：
+1. [新 Issue 分流与重复检测](examples/README.md#示例一新-issue-分流)
+2. [PR 风险审查与 CI 诊断](examples/README.md#示例二pr-风险审查)
+3. [周报与 Release 草稿](examples/README.md#示例三周报与-release-草稿)
-- "看看这个仓库有什么新 Issue？"
-- "帮我审查这个 PR"
-- "这个 Issue 该怎么回复？"
-- "生成这周的运营报告"
-- "帮我管理过期 Issue"
+### 安装为 Agent Skill
-每个操作都会先生成草稿展示给你确认，明确同意后才执行。
+必须保留完整仓库结构；`SKILL.md` 会引用 `references/`。
----
+| 平台 | 用户级安装 | 调用方式 |
+| --- | --- | --- |
+| ChatGPT（Codex 模式）/ Codex CLI | `git clone https://github.com/hyt315/github-oss-ops.git ~/.agents/skills/github-oss-ops` | 提示词中使用 `$github-oss-ops`，或通过 `/skills` 选择 |
+| Claude Code | `git clone https://github.com/hyt315/github-oss-ops.git ~/.claude/skills/github-oss-ops` | 要求 Claude 使用 `github-oss-ops` skill |
+| Cursor | `git clone https://github.com/hyt315/github-oss-ops.git ~/.cursor/skills/github-oss-ops` | 要求 Cursor Agent 使用 `github-oss-ops` skill |
-## 📥 安装 / Installation
+项目级安装可分别使用 `.agents/skills/github-oss-ops`、`.claude/skills/github-oss-ops` 或 `.cursor/skills/github-oss-ops`。新安装没有被发现时，重启对应 Agent。
-| 平台 | 安装命令 |
-|------|----------|
-| **Claude Code** | `git clone https://github.com/hyt315/github-oss-ops.git ~/.claude/skills/github-oss-ops` |
-| **Codex** | `git clone https://github.com/hyt315/github-oss-ops.git ~/.codex/skills/github-oss-ops` |
-| **Cursor** | `git clone https://github.com/hyt315/github-oss-ops.git ~/.cursor/skills/github-oss-ops` |
+Windows PowerShell：
-> 安装后 Skill 自动生效，无需额外配置。需要 GitHub 访问权限（PAT 或 MCP），首次使用时 Skill 会自动引导配置。
-
----
-
-## 📥 下载 / Download
-
-| 方式 | 命令 / 链接 |
-|------|------------|
-| **HTTPS** | `git clone https://github.com/hyt315/github-oss-ops.git` |
-| **SSH** | `git clone git@github.com:hyt315/github-oss-ops.git` |
-| **GitHub CLI** | `gh repo clone hyt315/github-oss-ops` |
-| **ZIP 源码** | [下载 ZIP](https://github.com/hyt315/github-oss-ops/archive/refs/heads/main.zip) |
-| **Tar 源码** | [下载 Tar](https://github.com/hyt315/github-oss-ops/archive/refs/heads/main.tar.gz) |
+```powershell
+git clone https://github.com/hyt315/github-oss-ops.git "$HOME\.agents\skills\github-oss-ops"
+```
----
+### 下载
-## 💡 核心理念
+```bash
+# HTTPS
+git clone https://github.com/hyt315/github-oss-ops.git
-- **只起草，不发送**：所有操作都先生成草稿展示给你，确认后才执行
-- **渐进式运营**：不需要一次配置全部，按需使用各功能模块
-- **维护者视角**：帮助个人维护者或小型团队降低维护负担
+# SSH
+git clone git@github.com:hyt315/github-oss-ops.git
----
+# GitHub CLI
+gh repo clone hyt315/github-oss-ops
-## 📁 文件结构
+# main 分支 ZIP
+curl -L https://github.com/hyt315/github-oss-ops/archive/refs/heads/main.zip -o github-oss-ops-main.zip
-```
-github-oss-ops/
-├── SKILL.md # Skill 核心定义
-├── README.md # 本文件
-├── LICENSE # MIT 协议
-├── .gitignore # Git 忽略规则
-├── CONTRIBUTING.md # 贡献指南
-├── CODE_OF_CONDUCT.md # 行为准则
-├── SECURITY.md # 安全策略
-├── .github/
-│ ├── pull_request_template.md # PR 模板
-│ └── ISSUE_TEMPLATE/
-│ ├── bug_report.yml # Bug 报告表单
-│ ├── feature_request.yml # 功能建议表单
-│ └── doc_improvement.yml # 文档改进表单
-└── references/ # 参考文件
- ├── automation-templates.md # 自动化配置模板
- ├── github-access-guide.md # GitHub 访问指南
- ├── triage-workflow.md # Issue 分流工作流
- ├── response-templates.md # 回复模板库
- ├── pr-review-guide.md # PR 审查指南
- └── release-workflow.md # 发版工作流
+# 只查看技能合同（单文件不是完整安装）
+curl -L https://raw.githubusercontent.com/hyt315/github-oss-ops/main/SKILL.md -o SKILL.md
```
----
+浏览器入口：[最新 Release](https://github.com/hyt315/github-oss-ops/releases/latest) · [main ZIP](https://github.com/hyt315/github-oss-ops/archive/refs/heads/main.zip)
-## 🤝 贡献
+### 五分钟开始
-请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+安装后可以直接说：
----
-
-## 📄 许可
+```text
+使用 $github-oss-ops 扫描 hyt315/notebook-video 最近 7 天的 Issue、PR 和 CI。
+先做只读分析，给出需要关注的项目和回复草稿；未经我确认不要评论、打标签、关闭、合并或发布。
+```
-[MIT](LICENSE)
+公开仓库的只读分析不需要 Token。需要写入 GitHub 时，优先使用平台官方 GitHub 连接、GitHub 官方 MCP 的 OAuth，或已登录的 `gh`；再考虑最小权限、限定仓库、设置有效期的 fine-grained PAT。
----
+Skill 不会要求你把 Token 发到聊天中，不会扫描用户主目录寻找凭据，也不会打印或写入 Token。完整认证与故障排查见 [references/github-access-guide.md](references/github-access-guide.md)。
-## English
+### 安全模型
-## 📖 What is this?
+- 只读扫描、分类和草稿生成可以直接执行。
+- 评论、标签、指派、关闭、合并、推送、规则修改和 Release 都是外部写操作，必须在目标与内容明确后获得批准。
+- 安全漏洞只进入 GitHub Private Vulnerability Reporting 等私密渠道。
+- 批量操作先小批预览，并设置上限；不自动关闭、不自动合并。
+- 所有统计报告标注时间窗口，不把缺失数据写成事实。
-**GitHub OSS Ops** is an AI Agent Skill for day-to-day open-source repository maintenance. It automates Issue triage, drafts replies, assists with PR reviews, manages releases, handles stale items, and generates operations reports.
+### 仓库结构与验证
-> 💡 Works alongside [github-oss-prep](https://github.com/hyt315/github-oss-prep): oss-prep handles project launch prep, this skill handles post-launch operations.
+- `SKILL.md`：主工作流与批准边界。
+- `references/`：分流、回复、PR、Release、认证和自动化参考。
+- `examples/`：三个端到端输出示例。
+- `scripts/validate-skill.mjs`：结构、链接、版本和隐私静态检查。
+- `.github/workflows/validate.yml`：PR 与主分支 CI。
-### ✨ Core Features
-
-| Module | Description |
-|--------|-------------|
-| 🔍 **Issue Scanning** | Scan unread Issues, auto-classify by type (Bug/Feature/Question/Docs) |
-| ✍️ **Smart Replies** | Draft context-aware replies based on templates with status/label suggestions |
-| 📋 **PR Review** | Rule-based PR review: title format, impact, sensitive info, workflow alignment |
-| 📦 **Release Management** | Auto-generate release notes, calculate Semantic Version from Conventional Commits |
-| 🧹 **Stale Cleanup** | Scan stale Issues/PRs, draft close or reminder replies |
-| 📊 **Ops Reports** | Generate stats: open/close trends, response times, active contributors |
-| ⚙️ **Automation Setup** | Generate GitHub Actions workflows for automated Issue management |
+```bash
+node scripts/validate-skill.mjs
+```
----
+### 许可证与贡献
-## 🚀 Quick Start
+项目使用 [MIT License](LICENSE)。参与前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、[SECURITY.md](SECURITY.md) 和 [CONTRIBUTORS.md](CONTRIBUTORS.md)。
-This is an AI Agent Skill — install it in any AI coding assistant and it's ready to use.
+## English
-### How to use
+GitHub OSS Ops is an approval-gated Agent Skill for maintainers who need repeatable Issue triage, PR review assistance, release preparation, stale-item review and repository health reporting.
-Once installed, simply tell your AI assistant what you need:
+### Key behavior
-- "Check for new Issues in this repo"
-- "Review this PR for me"
-- "How should I reply to this Issue?"
-- "Generate this week's operations report"
-- "Help me clean up stale Issues"
+- Public read-only analysis works without credentials.
+- The skill drafts before it comments, labels, closes, merges, pushes or releases.
+- Authentication prefers an official GitHub connection or OAuth, then an authenticated GitHub CLI, then a repository-scoped fine-grained PAT.
+- It never searches a home directory for credentials, prints tokens or asks users to paste secrets into chat.
+- Three inspectable workflows live in [examples/README.md](examples/README.md).
-Every action drafts first, shows you for review, then executes only after your approval.
+### Install
----
+```bash
+# Codex / ChatGPT Codex mode
+git clone https://github.com/hyt315/github-oss-ops.git ~/.agents/skills/github-oss-ops
-## 📁 File Structure
+# Claude Code
+git clone https://github.com/hyt315/github-oss-ops.git ~/.claude/skills/github-oss-ops
+# Cursor
+git clone https://github.com/hyt315/github-oss-ops.git ~/.cursor/skills/github-oss-ops
```
-github-oss-ops/
-├── SKILL.md # Core skill definition
-├── README.md # This file
-├── LICENSE # MIT License
-├── .gitignore # Git ignore rules
-├── CONTRIBUTING.md # Contribution guide
-├── CODE_OF_CONDUCT.md # Code of conduct
-├── SECURITY.md # Security policy
-├── .github/
-│ ├── pull_request_template.md # PR template
-│ └── ISSUE_TEMPLATE/
-│ ├── bug_report.yml # Bug report form
-│ ├── feature_request.yml # Feature request form
-│ └── doc_improvement.yml # Docs improvement form
-└── references/ # Reference documents (6 files)
-```
-
----
-
-## 🤝 Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md).
----
+Validate with `node scripts/validate-skill.mjs`. See the Chinese section above for download methods, operating boundaries and the repository map.
-## 📄 License
+### Sources
-[MIT](LICENSE)
+The authentication and tool guidance follows the [official GitHub MCP Server](https://github.com/github/github-mcp-server) and GitHub's documentation for [fine-grained personal access tokens](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [repository topics](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) and [private vulnerability reporting](https://docs.github.com/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository).
diff --git a/SECURITY.md b/SECURITY.md
index f9fb15d..735e06c 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,24 +1,23 @@
-# 安全策略 / Security Policy
+# Security Policy
-## 报告漏洞 / Reporting a Vulnerability
+## Reporting a vulnerability
-如果你发现安全漏洞，请通过以下方式报告：
+Report vulnerabilities through [GitHub Private Vulnerability Reporting](https://github.com/hyt315/github-oss-ops/security/advisories/new).
-If you discover a security vulnerability, please report it via:
+Do not open a public Issue containing exploit details, credentials, private repository data or personal information. If Private Vulnerability Reporting is unavailable, open a public Issue that only asks the maintainer to enable a private channel; do not include sensitive details.
-- **GitHub Issues**: [提交安全报告](https://github.com/hyt315/github-oss-ops/issues/new?template=bug_report.yml)（请勿公开敏感细节）
-- **Private vulnerability reporting**: 本仓库已启用 GitHub 私密漏洞报告功能
+## Credential safety
-我们将尽快确认并修复。
+GitHub OSS Ops must never:
-We will acknowledge and address the report as quickly as possible.
+- ask a user to paste a PAT, API key or password into chat;
+- search a home directory, editor configuration, MCP configuration or shell history for credentials;
+- print, log, commit or persist credentials in the skill directory;
+- place credentials in a Git remote URL;
+- request broader GitHub permissions than the approved operation requires.
-## 支持版本 / Supported Versions
+If a credential appears in chat, logs or a commit, stop the affected write operation, advise immediate revocation/rotation and verify the repository history before release.
-| 版本 / Version | 支持状态 / Supported |
-|---------------|:-------------------:|
-| latest | ✅ |
+## Supported versions
-## 免责声明 / Disclaimer
-
-本 Skill 仅处理公开数据，不会收集或存储用户凭据。
+Only the latest published release is actively supported.
diff --git a/SKILL.md b/SKILL.md
index 6902406..ef5b238 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,7 +1,7 @@
---
name: github-oss-ops
-version: 1.0.2
-description: Use when managing open source GitHub repositories — covers Issue triage, smart replies, PR review assistance, version/release management, stale management, and operations reporting. Triggers: Issue 管理、分流、triage、看看有没有新 Issue、PR 审查、回复 Issue、版本号、发版、Release、changelog、过期 Issue、stale、运营报告、开源项目运营、oss ops、project operations.
+version: 1.1.0
+description: Use when maintaining an open-source GitHub repository after launch, including Issue triage, reply drafting, PR review assistance, CI diagnosis, release preparation, stale-item review, repository health reporting, and approval-gated GitHub writes. Triggers include Issue 管理、分流、triage、PR 审查、回复 Issue、版本号、发版、Release、changelog、过期 Issue、stale、运营报告、开源项目运营、oss ops, and project operations.
---
# GitHub 开源项目运营
@@ -10,30 +10,30 @@ description: Use when managing open source GitHub repositories — covers Issue
## 核心理念
-- **只起草，不发送**：所有回复和标签操作都先展示给用户确认，明确同意才执行
+- **读写分离**：公开信息读取、分析和草稿可直接进行；评论、标签、关闭、合并、推送、设置和发布等外部写操作必须明确目标与内容，并在执行前获得批准
- **维护者视角**：帮助个人维护者或小型团队高效管理项目，降低维护负担
- **渐进式运营**：不需要一次配置全部，按需使用各功能模块
- **与 github-oss-prep 配合**：oss-prep 负责发布，本技能负责发布后的日常运营
+- **凭据零采集**：不要求用户把 Token 发到聊天，不搜索用户目录或配置文件提取凭据，不打印、记录或写入凭据
+- **能力发现优先**：根据当前平台实际提供的 GitHub 连接、MCP、CLI 或 API 能力选择路径，不假定某个工具名永久存在
---
## 前置条件
-需要 GitHub 访问凭据（三选一）：
+公开仓库的只读扫描不要求认证。只有读取私有数据或执行写操作时才需要 GitHub 授权。
-1. **GitHub PAT**（推荐 Fine-grained PAT，Classic PAT 亦可）
- - Fine-grained PAT（`github_pat_` 前缀）：可限定仓库和权限，更安全
- - Classic PAT（`ghp_` 前缀）：需 `repo` 权限，配置最简单
-2. **GitHub MCP 工具**（推荐）：官方 `github/github-mcp-server`，通过 Docker 运行
- - 可用工具：`list_issues`、`issue_read`、`issue_write`、`add_issue_comment` 等
-3. **GitHub CLI（`gh`）**：安装 `gh` 并执行 `gh auth login`，适合交互式操作
-4. **curl + REST API**：以上均不可用时的回退方案
+按以下优先级使用当前环境已经提供的能力：
-配置方式（PAT）：
-- 环境变量：设置 `GITHUB_TOKEN` 或 `GITHUB_PERSONAL_ACCESS_TOKEN`
-- MCP Server 配置文件：将 PAT 填入对应工具的 `env` 中
+1. **平台官方 GitHub 连接器或 GitHub 官方远程 MCP（OAuth）**：由受信任界面完成授权。
+2. **已认证的 GitHub CLI**：先运行 `gh auth status`；未登录时让用户在受信任终端完成 `gh auth login --web`。
+3. **GitHub 官方本地 MCP Server**：适合需要本地宿主或受控 toolsets 的环境。
+4. **Fine-grained PAT**：仅在用户明确选择时使用，限定仓库、最小权限并设置有效期，由受信任的密码输入或环境管理接收。
+5. **公开 REST API / 网页**：作为只读或人工交接回退。
-详细的 PAT 生成步骤（含 Fine-grained PAT）、各工具 MCP 配置模板、GitHub CLI 用法、MCP 工具清单和 curl + REST API 回退方案，参见 [references/github-access-guide.md](references/github-access-guide.md)。
+不得从用户主目录、编辑器配置、MCP JSON、Shell 历史或进程环境中主动寻找 Token；不得输出 Token 值。不得把 Classic PAT 描述为默认或最简单的推荐方案。
+
+授权方式、最小权限、能力探测和回退流程见 [references/github-access-guide.md](references/github-access-guide.md)。
---
@@ -71,7 +71,7 @@ Step 9: 自动化配置（按需生成 GitHub Actions 模板）
2. 如果是，提取 `owner/repo` 信息
3. 如果不是，询问用户要管理哪个仓库
-确认仓库后，检查仓库是否为公开仓库（本技能面向开源项目）。
+确认仓库后，记录 `owner/repo`、默认分支、可见性和当前用户权限。若是公开仓库，先完成无需认证的只读工作；若是私有仓库，说明本技能仍可使用，但它不属于公开开源运营场景，且必须通过受信任连接获得授权。
---
@@ -500,8 +500,8 @@ Step 9: 自动化配置（按需生成 GitHub Actions 模板）
| 没有未关闭的 Issue | 输出"一切正常"，不生成多余报告 |
| Issue 数量超过 100 | 分批处理，优先处理最近的 |
| API 速率限制 | 等待或提示用户稍后重试（已认证 5000 次/小时，未认证 60 次/小时） |
-| MCP 工具不可用 | 回退到 GitHub CLI（`gh`）或 curl + REST API |
-| Docker 未运行 | MCP Server 无法启动，提示用户启动 Docker 或使用 `gh` CLI / curl 回退方案 |
+| MCP 工具不可用 | 继续完成公开只读分析；写操作回退到已认证的 `gh`、受信任连接或人工交接 |
+| Docker 未运行 | 优先使用官方远程 MCP/OAuth、`gh` 或网页，不把 Docker 作为阻塞条件 |
| Windows PowerShell 环境 | curl 示例中 `$GITHUB_TOKEN` 需改为 `$env:GITHUB_TOKEN`，行续接符 `\` 改为 `` ` `` |
| Fine-grained PAT 权限不足 | 提示用户检查 PAT 的仓库范围和权限级别（Issues/PR 需 Read and write） |
| 用户取消操作 | 不执行任何已准备好的操作 |
diff --git a/agents/openai.yaml b/agents/openai.yaml
new file mode 100644
index 0000000..a779b2a
--- /dev/null
+++ b/agents/openai.yaml
@@ -0,0 +1,10 @@
+interface:
+ display_name: GitHub OSS Ops
+ short_description: Operate open-source GitHub repositories with approval-gated workflows
+ default_prompt: Use $github-oss-ops to scan this repository, draft a prioritized maintenance plan, and request approval before any external write.
+policy:
+ products:
+ - chatgpt
+ - codex
+ - api
+ allow_implicit_invocation: true
diff --git a/assets/social-preview.png b/assets/social-preview.png
new file mode 100644
index 0000000..4b0f174
Binary files /dev/null and b/assets/social-preview.png differ
diff --git a/assets/social-preview.svg b/assets/social-preview.svg
new file mode 100644
index 0000000..67f3218
--- /dev/null
+++ b/assets/social-preview.svg
@@ -0,0 +1,62 @@
+
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..a1b65f8
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,70 @@
+# GitHub OSS Ops examples
+
+These examples make the skill's output and approval boundaries inspectable before installation. Repository names and issue text are illustrative; the workflow and fields are the enforced contract.
+
+## 示例一：新 Issue 分流
+
+**Prompt**
+
+```text
+扫描 owner/repo 最近 7 天的新 Issue。识别重复项、类型、优先级和需要补充的信息。先给草稿，不要写入 GitHub。
+```
+
+**Expected read-only output**
+
+```text
+时间窗口：2026-07-11 至 2026-07-18
+Issue #42 — Windows 渲染失败
+分类：type:bug / priority:high
+证据：包含可复现命令；CI 中 Windows job 同类失败
+可能重复：#37（相同错误码，仍需维护者确认）
+建议：请求系统版本和最小复现仓库
+草稿：感谢反馈。为了确认是否与 #37 相同，请补充……
+
+待批准写操作：添加 type:bug、priority:high；发送上述评论。
+```
+
+只有用户确认具体 Issue、标签和评论内容后，才执行写操作。
+
+## 示例二：PR 风险审查
+
+**Prompt**
+
+```text
+审查 PR #57。检查改动范围、测试、敏感信息、CI、兼容性和发布影响，不要提交 Review 或合并。
+```
+
+**Expected output**
+
+```text
+结论：Request changes（草稿）
+高风险：工作流从 pull_request 改为 pull_request_target，并读取 PR 分支脚本
+中风险：新增依赖未更新锁文件
+已通过：单元测试、格式检查
+缺失：威胁说明、最小权限 permissions
+建议 Review：请恢复 pull_request，或说明为何必须使用 pull_request_target……
+
+待批准写操作：提交 Request changes Review。
+```
+
+## 示例三：周报与 Release 草稿
+
+**Prompt**
+
+```text
+生成本周运营报告，并根据 v1.2.0 之后已合并 PR 起草下一版 Release。不要创建 Tag 或 Release。
+```
+
+**Expected output**
+
+```text
+统计窗口：2026-07-11 00:00Z 至 2026-07-18 00:00Z
+新 Issue 8 / 关闭 6 / 净增加 2
+新 PR 5 / 合并 4 / 关闭未合并 1
+首次响应中位数：9.4 小时（样本 7）
+建议版本：v1.3.0
+依据：2 个向后兼容功能、3 个修复、1 个文档更新
+Release 草稿：Added … / Fixed … / Documentation …
+
+待批准写操作：版本文件 PR、Tag、GitHub Release（分别确认）。
+```
diff --git a/references/automation-templates.md b/references/automation-templates.md
index 8ead3bf..940ccca 100644
--- a/references/automation-templates.md
+++ b/references/automation-templates.md
@@ -38,7 +38,7 @@ jobs:
stale:
runs-on: ubuntu-latest
steps:
- - uses: actions/stale@v10
+ - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10
with:
# Issue 配置
days-before-issue-stale: 30 # 30 天无活动标记 stale
@@ -126,7 +126,7 @@ jobs:
label:
runs-on: ubuntu-latest
steps:
- - uses: github/issue-labeler@v3.4
+ - uses: github/issue-labeler@c1b0f9f52a63158c4adc09425e858e87b32e9685 # v3.4
with:
configuration-path: .github/labeler.yml
enable-versioned-regex: 0
@@ -160,7 +160,7 @@ jobs:
welcome:
runs-on: ubuntu-latest
steps:
- - uses: actions/first-interaction@v3
+ - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # v3
with:
issue_message: |
## Welcome! 👋
@@ -169,7 +169,7 @@ jobs:
A few tips:
- Please make sure you've searched existing issues to avoid duplicates
- - Check [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines
+ - Check [CONTRIBUTING.md](https://github.com/${{ github.repository }}/blob/${{ github.event.repository.default_branch }}/CONTRIBUTING.md) for guidelines
- Be patient — maintainers will review your issue as soon as possible
We appreciate your contribution!
@@ -224,7 +224,7 @@ jobs:
assign:
runs-on: ubuntu-latest
steps:
- - uses: pozil/auto-assign-issue@v4
+ - uses: pozil/auto-assign-issue@af6beea6bdf1e8eb373f061c5bc168681fc6d011 # v4.0.1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
assignees: your-github-username # 替换为你的 GitHub 用户名
@@ -236,7 +236,7 @@ jobs:
如果有多个维护者，可以用轮询（round-robin）方式分配：
```yaml
- - uses: pozil/auto-assign-issue@v4
+ - uses: pozil/auto-assign-issue@af6beea6bdf1e8eb373f061c5bc168681fc6d011 # v4.0.1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
assignees: user1, user2, user3
@@ -269,7 +269,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check issue health
- uses: actions/github-script@v9
+ uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
with:
script: |
const { data: issues } = await github.rest.issues.listForRepo({
diff --git a/references/github-access-guide.md b/references/github-access-guide.md
index a325bfb..cc95d8f 100644
--- a/references/github-access-guide.md
+++ b/references/github-access-guide.md
@@ -1,550 +1,119 @@
-# GitHub 访问配置指南
+# GitHub access guide
-> 本技能需要 GitHub 访问凭据才能操作 Issue 和 PR。本文件说明如何获取和配置。
+This guide defines how GitHub OSS Ops selects an access path without collecting credentials.
----
+## Decision order
-## 目录
+### 1. Public read-only work
-- [什么是 PAT](#什么是-pat)
-- [第一步：生成 PAT](#第一步生成-pat)
-- [第二步：配置到 MCP Server](#第二步配置到-mcp-server)
-- [第三步：验证](#第三步验证)
-- [GitHub CLI（gh）方式](#github-cligh-方式)
-- [Token 自动发现策略](#token-自动发现策略)
-- [MCP 工具清单](#mcp-工具清单)
-- [curl + REST API 回退方案](#curl--rest-api-回退方案)
-- [常见问题](#常见问题)
+Public repository metadata, files, Issues, PRs, releases and Actions status can usually be read without authentication. Complete all useful read-only analysis first. Authentication failure must not block an offline draft or manual handoff.
----
+### 2. Official GitHub connection or remote MCP
-## 什么是 PAT
+Prefer a platform-provided GitHub connector or the [official GitHub MCP Server](https://github.com/github/github-mcp-server). The hosted remote server supports OAuth in compatible hosts and avoids manually handling a PAT.
-PAT（Personal Access Token）是 GitHub 的个人访问令牌，用于 API 认证。GitHub 提供两种：
+Do not assume fixed tool names. Inspect the capabilities exposed by the current host, then map the operation by purpose:
-- **Classic PAT**（`ghp_` 前缀）：传统令牌，通过 scope 授权，权限范围较宽
-- **Fine-grained PAT**（`github_pat_` 前缀）：细粒度令牌，可限定到特定仓库，更安全但配置更复杂
+| Purpose | Typical capability |
+| --- | --- |
+| Repository files and metadata | repository/file read |
+| Issue list, details and comments | issue read/list |
+| Issue labels, state and comments | issue write/comment |
+| PR diff, checks, reviews and merge | pull-request read/write/review |
+| Workflow runs and logs | Actions list/get |
+| Tags and releases | release/tag API, GitHub CLI or REST fallback |
-### 如何选择
+The official MCP Server supports toolsets and individual-tool allow-lists. Enable only the groups needed for the task; read-only mode is appropriate for audits.
-| 特性 | Classic PAT | Fine-grained PAT |
-|------|-------------|------------------|
-| 权限粒度 | 按 scope（如 `repo`） | 按仓库 + 按权限（如 `Issues: Write`） |
-| 仓库范围 | 所有可访问仓库 | 可限定到特定仓库 |
-| 安全性 | 较低（泄露即全仓库） | 较高（泄露仅限授权仓库） |
-| 过期时间 | 可设 No expiration | 必须设过期时间（最长 1 年） |
-| 配置难度 | 简单（勾选 `repo`） | 稍复杂（逐项选择权限） |
-| GitHub 推荐 | 兼容性最好 | **推荐用于生产环境** |
+### 3. GitHub CLI
-**本技能推荐**：个人项目用 Classic PAT（配置最简单），正式维护的开源项目用 Fine-grained PAT（更安全）。
-
----
-
-## 第一步：生成 PAT
-
-### 方式 A：生成 Classic PAT（简单）
-
-1. 打开 https://github.com/settings/tokens/new
-
-2. 点击 **Generate new token (classic)**
-
-3. 填写：
- - **Note**：`github-oss-ops`（备注名称，随意）
- - **Expiration**：选择过期时间（建议 90 天，不建议 No expiration）
- - **Select scopes**：勾选 `repo`（完整仓库访问权限）
-
-4. 点击 **Generate token**
-
-5. **立即复制 token**（`ghp_` 开头的字符串），页面刷新后无法再次查看
-
-### 方式 B：生成 Fine-grained PAT（更安全）
-
-1. 打开 https://github.com/settings/personal-access-tokens/new
-
-2. 填写：
- - **Token name**：`github-oss-ops`
- - **Expiration**：建议 90 天（最长 1 年，到期需重新生成）
- - **Repository access**：选择 **Only select repositories**，勾选要管理的仓库
-
-3. 在 **Repository permissions** 中，按需勾选以下权限：
-
- | 权限 | 级别 | 用途 |
- |------|------|------|
- | Issues | Read and write | Issue 管理（读取、更新、评论） |
- | Pull requests | Read and write | PR 管理（读取、审查、合并） |
- | Metadata | Read-only | 仓库基本信息（必选） |
- | Labels | Read and write | 标签管理 |
- | Contents | Read-only | 读取文件（PR 改动分析） |
- | Commit statuses | Read-only | CI/CD 状态检查 |
- | Members | Read-only | 贡献者信息 |
-
-4. 点击 **Generate token**
-
-5. **立即复制 token**（`github_pat_` 开头的字符串）
-
----
-
-## 第二步：配置到 MCP Server
-
-GitHub 官方 MCP Server（`github/github-mcp-server`）提供两种部署方式：
-
-- **远程服务器**（推荐）：GitHub 托管，通过 OAuth 认证，无需 Docker
-- **本地服务器**：通过 Docker 运行，使用 PAT 认证
-
-> **重要**：旧的 `@modelcontextprotocol/server-github`（npx 方式）已不再维护，请迁移至官方 `github/github-mcp-server`。下方配置均使用官方版本。
-
-### 前置条件（本地服务器方式）
-
-- 安装 [Docker](https://www.docker.com/) 并确保 Docker 正在运行
-- Docker 镜像：`ghcr.io/github/github-mcp-server`（公开镜像，无需登录）
-
-### Cursor
-
-编辑 `~/.cursor/mcp.json`：
-
-```json
-{
- "mcpServers": {
- "github": {
- "command": "docker",
- "args": [
- "run", "-i", "--rm",
- "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
- "ghcr.io/github/github-mcp-server"
- ],
- "env": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token"
- }
- }
- }
-}
-```
-
-### Claude Desktop
-
-编辑配置文件：
-- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
- "mcpServers": {
- "github": {
- "command": "docker",
- "args": [
- "run", "-i", "--rm",
- "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
- "ghcr.io/github/github-mcp-server"
- ],
- "env": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token"
- }
- }
- }
-}
-```
-
-### Windsurf
-
-编辑 `~/.codeium/mcp_config.json`：
-
-```json
-{
- "mcpServers": {
- "github": {
- "command": "docker",
- "args": [
- "run", "-i", "--rm",
- "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
- "ghcr.io/github/github-mcp-server"
- ],
- "env": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token"
- }
- }
- }
-}
-```
-
-> 注意：Windsurf 可能不支持环境变量引用，需要直接在 `env` 中硬编码 token。
-
-### VS Code / GitHub Copilot
-
-在项目根目录创建或编辑 `.vscode/mcp.json`：
-
-```json
-{
- "inputs": [
- {
- "type": "promptString",
- "id": "github_token",
- "description": "GitHub Personal Access Token",
- "password": true
- }
- ],
- "servers": {
- "github": {
- "command": "docker",
- "args": [
- "run", "-i", "--rm",
- "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
- "ghcr.io/github/github-mcp-server"
- ],
- "env": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
- }
- }
- }
-}
-```
-
-> 注意：VS Code 使用 `servers` 而非 `mcpServers` 作为顶层键名。`${input:github_token}` 方式会在首次使用时弹窗输入 token，避免硬编码。
-
-### 远程服务器方式（无需 Docker）
-
-如果你的 MCP 客户端支持远程 MCP 服务器（VS Code 1.101+、Claude Desktop、Cursor 等），可以直接使用 GitHub 托管的远程服务器，通过 OAuth 认证，无需 PAT 和 Docker：
-
-```json
-{
- "servers": {
- "github": {
- "type": "http",
- "url": "https://api.githubcopilot.com/mcp/"
- }
- }
-}
-```
-
-首次使用时会弹出浏览器窗口完成 OAuth 授权。详见 [GitHub MCP Server 文档](https://github.com/github/github-mcp-server)。
-
-### 通用方式（环境变量）
-
-如果不想使用 MCP，也可以直接设置环境变量，配合 GitHub CLI 或 curl 使用：
-
-```powershell
-# Windows PowerShell
-$env:GITHUB_TOKEN = "ghp_你的token"
-```
-
-```bash
-# Linux / macOS
-export GITHUB_TOKEN="ghp_你的token"
-```
-
----
-
-## 第三步：验证
-
-### 验证 PAT
-
-```bash
-# Linux / macOS
-curl -sI -H "Authorization: token $GITHUB_TOKEN" \
- https://api.github.com/user
-```
-
-```powershell
-# Windows PowerShell
-curl -sI -H "Authorization: token $env:GITHUB_TOKEN" `
- https://api.github.com/user
-```
-
-响应头中 `x-oauth-scopes` 应包含 `repo`（Classic PAT），如：
-```
-x-oauth-scopes: repo, workflow
-```
-
-> Fine-grained PAT 的响应头中 `x-oauth-scopes` 为空，需检查 `x-accepted-github-permissions` 确认权限。
-
-### 验证 MCP Server
-
-启动 MCP 客户端后，尝试调用一个简单工具（如 `list_issues`），如果返回数据说明配置成功。如果报错，检查 Docker 是否运行、token 是否正确。
-
----
-
-## GitHub CLI（gh）方式
-
-除了 MCP 和 curl，GitHub 官方 CLI 工具 `gh` 是更便捷的替代方案，语法简洁且支持认证管理。
-
-### 安装
-
-| 平台 | 安装命令 |
-|------|----------|
-| Windows (winget) | `winget install GitHub.cli` |
-| Windows (scoop) | `scoop install gh` |
-| macOS (Homebrew) | `brew install gh` |
-| Linux (apt) | `sudo apt install gh` |
-
-详见 https://cli.github.com/
-
-### 认证
+Check authentication without exposing credentials:
```bash
-# 交互式登录（推荐，支持浏览器 OAuth）
-gh auth login
-
-# 使用 PAT 登录
-gh auth login --with-token < token.txt
-
-# 检查认证状态
gh auth status
-
-# 刷新权限（如需额外 scope）
-gh auth refresh -s read:project
```
-### 常用 Issue 管理命令
+If authentication is missing, the user should complete the browser flow in a trusted terminal:
```bash
-# 列出未关闭的 Issue
-gh issue list --repo owner/repo --state open
-
-# 查看某个 Issue 详情
-gh issue view 123 --repo owner/repo
-
-# 创建 Issue
-gh issue create --repo owner/repo --title "Bug: xxx" --body "描述"
-
-# 添加标签
-gh issue edit 123 --repo owner/repo --add-label "type:bug,priority:P1"
-
-# 添加评论
-gh issue comment 123 --repo owner/repo --body "回复内容"
-
-# 关闭 Issue
-gh issue close 123 --repo owner/repo --comment "已修复"
+gh auth login --web
```
-### 常用 PR 管理命令
+Useful commands:
```bash
-# 列出未关闭的 PR
-gh pr list --repo owner/repo --state open
-
-# 查看 PR 详情（含改动文件）
-gh pr view 456 --repo owner/repo
-gh pr diff 456 --repo owner/repo
-
-# 审查 PR
-gh pr review 456 --repo owner/repo --approve --body "LGTM"
-gh pr review 456 --repo owner/repo --request-changes --body "需要修改"
-
-# 合并 PR
-gh pr merge 456 --repo owner/repo --squash --delete-branch
+gh issue list --repo OWNER/REPO --state open
+gh pr checks 42 --repo OWNER/REPO
+gh pr view 42 --repo OWNER/REPO --json files,reviews,statusCheckRollup
+gh release list --repo OWNER/REPO
```
-> `gh` CLI 适合交互式操作和简单脚本。批量操作和复杂逻辑建议使用 MCP 工具或 REST API。
-
----
+### 4. Fine-grained PAT
-## Token 自动发现策略
+Use a PAT only when the user explicitly chooses it and no safer authorized connection is available.
-技能运行时按以下优先级自动查找 Token：
+- Prefer a fine-grained PAT over a classic PAT.
+- Limit repository access to the target repository.
+- Grant read-only permissions for audits.
+- Add write permissions only for the approved operation.
+- Set an expiration date and rotate on suspected exposure.
+- Let a trusted password prompt, credential manager or environment manager receive it.
-1. **环境变量**：读取 `GITHUB_TOKEN` 或 `GITHUB_PERSONAL_ACCESS_TOKEN`
- - bash：`echo $GITHUB_TOKEN`
- - PowerShell：`$env:GITHUB_TOKEN`
+Never ask the user to paste it into chat. Never inspect configuration files to extract it. Never print it to confirm that it exists.
-2. **MCP 配置文件**：在用户主目录下搜索包含 GitHub MCP 配置的 JSON 文件（深度 3 层）
- - Windows：`Get-ChildItem -Path $HOME -Recurse -Depth 3 -Filter *.json`
- - 匹配内容包含 `GITHUB_PERSONAL_ACCESS_TOKEN` 或 `mcpServers.*github` 的文件
+## Minimum-permission examples
-3. **兜底路径**（自动发现失败时参考）：
-
- | 路径 | 工具 |
- |------|------|
- | `~/.cursor/mcp.json` | Cursor |
- | `%APPDATA%\Claude\claude_desktop_config.json` | Claude Desktop (Windows) |
- | `~/.codeium/mcp_config.json` | Windsurf |
- | `.vscode/mcp.json` | VS Code |
-
-找到配置文件后，解析 JSON 提取 Token：
-
-```python
-import json
-d = json.load(open("<配置文件路径>"))
-for key in ('mcpServers', 'servers', 'mcp'):
- servers = d.get(key, {})
- if 'github' in servers:
- token = servers['github'].get('env', {}).get('GITHUB_PERSONAL_ACCESS_TOKEN', '')
- if token:
- print(token)
- break
-```
+| Operation | Repository permission |
+| --- | --- |
+| Read public Issues and PRs | none for public data; otherwise Issues/PR read |
+| Comment or label an Issue | Issues read/write |
+| Review or merge a PR | Pull requests read/write; Contents write may also be required |
+| Read workflow results | Actions read |
+| Create a Release | Contents write |
+| Change repository settings | Administration write |
-如所有方式都找不到，引导用户按上方步骤配置 PAT。
+Permission names and availability can vary by token type and repository ownership. Verify against GitHub's current authorization screen rather than copying a broad scope list.
----
+## REST fallback
-## MCP 工具清单
-
-本技能使用的 GitHub MCP 工具（基于官方 `github/github-mcp-server` 现行工具名）：
-
-> 官方 server 已把多个读取类工具整合为「通用工具 + `method` 参数」：`issue_read` 取代旧的 `get_issue`；`pull_request_read` 取代 `get_pull_request` / `get_pull_request_files` / `get_pull_request_status` 等；`issue_write` 取代 `create_issue` / `update_issue`；`pull_request_review_write` 取代 `create_pull_request_review`。若你的 MCP 客户端只暴露实际工具列表，以其为准。
-
-### Issue 操作
-
-| 工具 | 功能 | 底层 API |
-|------|------|----------|
-| `list_issues` | 列出仓库的 Issue（支持过滤状态、标签） | `GET /repos/{owner}/{repo}/issues` |
-| `issue_read`（method: `get`） | 获取单个 Issue 详情 | `GET /repos/{owner}/{repo}/issues/{number}` |
-| `issue_write` | 创建或更新 Issue（标签、状态、指派人） | `POST` / `PATCH /repos/{owner}/{repo}/issues` |
-| `add_issue_comment` | 添加 Issue 评论 | `POST /repos/{owner}/{repo}/issues/{number}/comments` |
-| `search_issues` | 搜索 Issue | `GET /search/issues` |
-
-### PR 操作
-
-| 工具 | 功能 | 底层 API |
-|------|------|----------|
-| `list_pull_requests` | 列出 PR | `GET /repos/{owner}/{repo}/pulls` |
-| `pull_request_read`（method: `get`） | 获取 PR 详情 | `GET /repos/{owner}/{repo}/pulls/{number}` |
-| `pull_request_read`（method: `get_files`） | 获取 PR 改动文件 | `GET /repos/{owner}/{repo}/pulls/{number}/files` |
-| `pull_request_read`（method: `get_status`） | 获取 PR 检查状态 | `GET /repos/{owner}/{repo}/commits/{sha}/status` |
-| `pull_request_read`（method: `get_comments`） | 获取 PR 评论 | `GET /repos/{owner}/{repo}/pulls/{number}/comments` |
-| `pull_request_read`（method: `get_reviews`） | 获取 PR 审查 | `GET /repos/{owner}/{repo}/pulls/{number}/reviews` |
-| `pull_request_review_write` | 提交 PR 审查意见 | `POST /repos/{owner}/{repo}/pulls/{number}/reviews` |
-| `merge_pull_request` | 合并 PR | `PUT /repos/{owner}/{repo}/pulls/{number}/merge` |
-
-### 其他
-
-| 工具 | 功能 |
-|------|------|
-| `search_repositories` | 搜索仓库 |
-| `get_file_contents` | 读取仓库文件 |
-| `list_commits` | 列出提交历史 |
-| `search_code` | 搜索代码 |
-| `search_users` | 搜索用户 |
-
----
-
-## curl + REST API 回退方案
-
-当 MCP 工具不可用时，通过 curl 直接调用 GitHub REST API：
-
-> **Windows PowerShell 用户注意**：
-> - 环境变量引用：将 `$GITHUB_TOKEN` 替换为 `$env:GITHUB_TOKEN`
-> - 行续接符：将 `\` 替换为 `` ` ``（反引号）
-> - JSON 字符串：PowerShell 中单引号内的 JSON 不需要转义，但双引号内的需要
-> - 推荐使用 `gh` CLI 替代 curl，语法更简洁且跨平台
-
-### 列出 Issue
+Use the current `Bearer` authorization form when an already-provisioned environment variable is available through a trusted runtime:
```bash
-# Linux / macOS
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
+curl --fail-with-body \
+ -H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos///issues?state=open&per_page=100"
+ -H "X-GitHub-Api-Version: 2022-11-28" \
+ https://api.github.com/repos/OWNER/REPO
```
-```powershell
-# Windows PowerShell
-curl -s -H "Authorization: token $env:GITHUB_TOKEN" `
- -H "Accept: application/vnd.github+json" `
- "https://api.github.com/repos///issues?state=open&per_page=100"
-```
+Do not run commands that echo the variable. Do not embed credentials in the URL. Redact request headers from debugging logs.
-### 获取 Issue 详情
+## Approval boundary
-```bash
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
- "https://api.github.com/repos///issues/"
-```
+Read-only calls can proceed when they are within the repository the user placed in scope. Before a write, show:
-### 添加 Issue 评论
+1. repository and exact target;
+2. proposed content or state change;
+3. whether it is reversible;
+4. expected follow-up, such as CI or notification effects.
-```bash
-curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
- -H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos///issues//comments" \
- -d '{"body":"评论内容"}'
-```
-
-### 更新 Issue（添加标签）
-
-```bash
-curl -s -X PATCH -H "Authorization: token $GITHUB_TOKEN" \
- -H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos///issues/" \
- -d '{"labels":["type:bug","priority:P1"]}'
-```
-
-### 列出 PR
-
-```bash
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
- "https://api.github.com/repos///pulls?state=open"
-```
-
-### 获取 PR 改动文件
-
-```bash
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
- "https://api.github.com/repos///pulls//files"
-```
+Approval for one comment does not authorize closing an Issue, merging a PR, publishing a Release or changing repository settings.
-### 提交 PR 审查
+## Failure handling
-```bash
-curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
- -H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos///pulls//reviews" \
- -d '{"body":"审查意见","event":"COMMENT"}'
-```
-
-> `event` 可选值：`APPROVE`（批准）、`REQUEST_CHANGES`（需要修改）、`COMMENT`（仅评论）
-
-### 列出标签
-
-```bash
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
- "https://api.github.com/repos///labels"
-```
+| Failure | Response |
+| --- | --- |
+| Public API rate limit | Continue with cloned files/local Git data; report freshness limits |
+| Authentication missing | Finish read-only/offline work; request trusted authorization only for the blocked write |
+| 401 | Do not retry repeatedly; verify auth state and rotate only if the credential is invalid |
+| 403 | Check repository selection and minimum permission for the exact operation |
+| 404 on a private repository | Treat as possible permission failure without revealing repository existence |
+| Connector or MCP unavailable | Use `gh`, public API or manual handoff; do not install an unofficial abandoned server |
+| Credential exposed | Stop, revoke/rotate, scan Git history and remove the value before continuing |
-### 创建标签
-
-```bash
-curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
- -H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos///labels" \
- -d '{"name":"type:bug","color":"d73a4a","description":"Confirmed bug"}'
-```
-
-### 搜索 Issue
-
-```bash
-curl -s -H "Authorization: token $GITHUB_TOKEN" \
- "https://api.github.com/search/issues?q=repo:/+is:issue+is:open+关键词"
-```
+## Authoritative references
-### API 速率限制
-
-- 已认证请求：5000 次/小时
-- 未认证请求：60 次/小时
-- 如遇到 `403 rate limit exceeded`，等待重置或减少操作频率
-- `actions/stale` 的 `operations-per-run` 参数可限制每次运行处理数量
-- 可通过 `GET /rate_limit` 接口查看当前剩余配额
-
----
-
-## 常见问题
-
-| 问题 | 解决 |
-|------|------|
-| token 生成后找不到 | 确保在 "Tokens (classic)" 页面生成 Classic PAT，在 "Fine-grained tokens" 页面生成 Fine-grained PAT |
-| 403 Forbidden | Classic PAT 的 scope 不够（重新勾选 `repo`）；Fine-grained PAT 权限不足（检查 Issues/PR 权限是否为 Read and write） |
-| 401 Bad credentials | token 过期或被撤销，重新生成 |
-| Docker 拉取镜像失败 | 执行 `docker logout ghcr.io` 后重试，或检查 Docker 是否运行 |
-| MCP 工具列表为空 | MCP Server 未启动，检查 Docker 是否运行、配置文件 JSON 是否正确 |
-| MCP Server 启动后立即退出 | 检查 token 是否有效，Docker 日志中通常有错误信息 |
-| API 返回空结果 | 确认仓库是公开仓库，或 token 有访问私有仓库的权限 |
-| PAT 被自动删除了 | GitHub 会清理一年未使用的 Classic PAT；Fine-grained PAT 到期后自动失效 |
-| Fine-grained PAT 无法操作 | 确认 Repository access 中已勾选目标仓库，且权限级别足够 |
-
-### 安全提醒
-
-- PAT 等同密码，不要分享给任何人
-- 不要提交到公开仓库（建议在 `.gitignore` 中添加 `.env`）
-- 建议设置过期时间，定期轮换（Fine-grained PAT 强制设过期时间）
-- GitHub 会自动删除一年未使用的 Classic PAT
-- 优先使用 Fine-grained PAT，将权限限制在特定仓库
-- 如怀疑 token 泄露，立即在 GitHub Settings → Tokens 中撤销
+- [GitHub MCP Server](https://github.com/github/github-mcp-server)
+- [Managing personal access tokens](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+- [Permissions required for fine-grained PATs](https://docs.github.com/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)
+- [GitHub CLI authentication](https://cli.github.com/manual/gh_auth_login)
diff --git a/references/release-workflow.md b/references/release-workflow.md
index e9ae91c..5c7c7b7 100644
--- a/references/release-workflow.md
+++ b/references/release-workflow.md
@@ -214,7 +214,7 @@ GET /repos/{owner}/{repo}/pulls?state=closed&sort=updated&direction=desc
```bash
curl -X POST \
- -H "Authorization: token $GITHUB_TOKEN" \
+ -H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/{owner}/{repo}/releases \
-d '{
@@ -229,7 +229,7 @@ curl -X POST \
### 方式二：通过 MCP 工具
-目前 GitHub MCP Server 没有直接的 `create_release` 工具。使用 curl 回退方案或通过 `create_or_update_file` 先推送版本文件变更，再用 `gh` CLI 创建 Release：
+先检查当前 GitHub 连接或 MCP 是否暴露 Release/Tag 写入能力。工具能力会更新，不要把某个工具名或缺失状态写死；没有相应能力时，使用已认证的 `gh` CLI 或 REST API：
```bash
gh release create v1.3.0 --title "v1.3.0" --notes "### Added..." --target main
diff --git a/references/response-templates.md b/references/response-templates.md
index 8d6f8fb..081fcf6 100644
--- a/references/response-templates.md
+++ b/references/response-templates.md
@@ -136,7 +136,7 @@ Feel free to open another issue if you have other ideas.
如果需要更多帮助，建议：
- 查阅文档：{文档链接}
-- 在 [Discussions](../../discussions) 中提问（问答类讨论更方便检索）
+- 在 Discussions 中提问：{repo_url}/discussions（问答类讨论更方便检索）
```
**英文**：
@@ -147,7 +147,7 @@ Here's how to solve this:
If you need more help:
- Check the docs: {docs link}
-- Ask in [Discussions](../../discussions) (Q&A discussions are easier to search)
+- Ask in Discussions: {repo_url}/discussions (Q&A discussions are easier to search)
```
### 信息不足
@@ -254,7 +254,7 @@ Please do not discuss this vulnerability publicly until a fix is released.
几个小提示：
- 提交 Issue 时可以使用模板，这样信息更完整
-- 如果想贡献代码，可以先看看 [CONTRIBUTING.md](../../blob/main/CONTRIBUTING.md)
+- 如果想贡献代码，可以先看看：{repo_url}/blob/{default_branch}/CONTRIBUTING.md
- 有任何问题随时在这里问
期待你的参与！
@@ -266,7 +266,7 @@ Thanks for your first contribution! Welcome to the project.
A few tips:
- Using issue templates helps provide complete information
-- If you'd like to contribute code, check out [CONTRIBUTING.md](../../blob/main/CONTRIBUTING.md) first
+- If you'd like to contribute code, check: {repo_url}/blob/{default_branch}/CONTRIBUTING.md first
- Feel free to ask any questions here
Looking forward to your contributions!
diff --git a/references/triage-workflow.md b/references/triage-workflow.md
index 3fb7c60..832ad10 100644
--- a/references/triage-workflow.md
+++ b/references/triage-workflow.md
@@ -126,7 +126,7 @@ for label in '{"name":"type:bug","color":"d73a4a","description":"Confirmed bug"}
'{"name":"resolution:invalid","color":"cfd3d7","description":"Invalid issue"}' \
'{"name":"good first issue","color":"7057ff","description":"Good for newcomers"}' \
'{"name":"help wanted","color":"008672","description":"Contributions welcome"}'; do
- curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
+ curl --fail-with-body -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
"https://api.github.com/repos///labels" \
-d "$label"
diff --git a/scripts/validate-skill.mjs b/scripts/validate-skill.mjs
new file mode 100644
index 0000000..04b0f46
--- /dev/null
+++ b/scripts/validate-skill.mjs
@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const expectedName = 'github-oss-ops';
+const expectedVersion = '1.1.0';
+const required = [
+ 'SKILL.md', 'README.md', 'LICENSE', 'CHANGELOG.md', 'CONTRIBUTING.md',
+ 'CODE_OF_CONDUCT.md', 'SECURITY.md', 'CONTRIBUTORS.md',
+ '.github/pull_request_template.md', '.github/ISSUE_TEMPLATE/config.yml',
+ '.github/repository-metadata.yml', 'agents/openai.yaml', 'examples/README.md',
+];
+
+const fail = (message) => {
+ console.error(`Validation failed: ${message}`);
+ process.exitCode = 1;
+};
+
+for (const relative of required) {
+ if (!fs.existsSync(path.join(root, relative))) fail(`missing ${relative}`);
+}
+
+const skill = fs.readFileSync(path.join(root, 'SKILL.md'), 'utf8');
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+const changelog = fs.readFileSync(path.join(root, 'CHANGELOG.md'), 'utf8');
+const metadata = fs.readFileSync(path.join(root, '.github/repository-metadata.yml'), 'utf8');
+
+if (!skill.startsWith('---\n')) fail('SKILL.md must start with YAML frontmatter');
+if (!skill.includes(`name: ${expectedName}`)) fail('SKILL.md name mismatch');
+if (!skill.includes(`version: ${expectedVersion}`)) fail('SKILL.md version mismatch');
+if (!/^description:\s*.+/m.test(skill)) fail('SKILL.md description is missing');
+if (!changelog.includes(`## [${expectedVersion}]`)) fail('CHANGELOG version mismatch');
+if (!metadata.includes(`tag: v${expectedVersion}`)) fail('repository release metadata mismatch');
+
+for (const fragment of [
+ `~/.agents/skills/${expectedName}`,
+ `~/.claude/skills/${expectedName}`,
+ `~/.cursor/skills/${expectedName}`,
+ 'https://github.com/hyt315/github-oss-ops/releases/latest',
+ 'examples/README.md',
+]) {
+ if (!readme.includes(fragment)) fail(`README missing ${fragment}`);
+}
+
+const ignored = new Set(['.git']);
+const files = [];
+const walk = (directory) => {
+ for (const entry of fs.readdirSync(directory, {withFileTypes: true})) {
+ if (ignored.has(entry.name)) continue;
+ const absolute = path.join(directory, entry.name);
+ if (entry.isDirectory()) walk(absolute);
+ else files.push(absolute);
+ }
+};
+walk(root);
+
+const textExtensions = new Set(['.md', '.yml', '.yaml', '.json', '.mjs', '.js', '.txt']);
+const secretPatterns = [
+ /ghp_[A-Za-z0-9]{20,}/,
+ /github_pat_[A-Za-z0-9_]{20,}/,
+ /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+ /AKIA[0-9A-Z]{16}/,
+];
+const bannedSafetyPatterns = [
+ /~\/\.codex\/skills\/github-oss-ops/,
+ /Get-ChildItem\s+-Path\s+\$HOME\s+-Recurse/i,
+ /print\s*\(\s*token\s*\)/i,
+ /echo\s+\$GITHUB_(?:TOKEN|PERSONAL_ACCESS_TOKEN)/,
+];
+
+for (const file of files) {
+ if (!textExtensions.has(path.extname(file))) continue;
+ const text = fs.readFileSync(file, 'utf8');
+ for (const pattern of secretPatterns) {
+ if (pattern.test(text)) fail(`credential-like value in ${path.relative(root, file)}`);
+ }
+ for (const pattern of bannedSafetyPatterns) {
+ if (pattern.test(text)) fail(`unsafe credential or install guidance in ${path.relative(root, file)}`);
+ }
+
+ if (path.extname(file) === '.md') {
+ for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+ const target = match[1].trim().split(/\s+/)[0];
+ if (/^(?:https?:|mailto:|#)/.test(target)) continue;
+ const local = decodeURIComponent(target.split('#')[0]);
+ if (!local) continue;
+ if (!fs.existsSync(path.resolve(path.dirname(file), local))) {
+ fail(`broken local link ${target} in ${path.relative(root, file)}`);
+ }
+ }
+ }
+}
+
+if (!process.exitCode) console.log(`${expectedName} v${expectedVersion} validation passed`);