skill-system-github

Skill System GitHub

通过 gh 执行一致的 GitHub 操作，并对工作流写入进行明确的安全检查，确保返回格式可预测。

决策矩阵

任务意图	操作	主要后端	备注
创建／列出／评论／关闭／重新打开议题	manage-issues	gh issue	创建新议题前先检查是否重复
创建／更新／删除标签，将标签应用到议题	manage-labels	gh label、gh issue edit	执行破坏性删除前先确认
列出／创建拉取请求	manage-prs	gh pr	强制推送到 main/master 时发出警告
初始化／更新议题模板	manage-templates	文件读写工具	直接编辑 .github/ISSUE_TEMPLATE/*
列出／检查／创建／更新工作流	manage-workflows	gh workflow、文件读写工具	推送工作流更改前运行 safety-check
根据令牌范围决定工作流推送路径	safety-check	gh auth status、gh api	缺少 workflow 范围时使用 API 回退方案

核心模式

模式 1：解析仓库并执行议题操作

gh issue list --repo <owner/repo> --state open --limit 50
gh issue create --repo <owner/repo> --title "<title>" --body "<body>"

模式 2：标签生命周期与议题标签应用

gh label create "<name>" --repo <owner/repo> --description "<desc>" --color "<hex>"
gh label edit "<name>" --repo <owner/repo> --new-name "<new>" --description "<desc>" --color "<hex>"
gh issue edit --repo <owner/repo> <number> --add-label "<label1>,<label2>"

模式 3：工作流可见性与近期运行检查

gh workflow list --repo <owner/repo>
gh run list --repo <owner/repo> --workflow "<name>" --limit 5

模式 4：写入 .github/workflows/* 前检查工作流范围

gh auth status
gh api repos/<owner>/<repo>/contents/.github/workflows/<file> \
  --method PUT \
  -f message="update workflow via api" \
  -f content="<base64-content>" \
  -f branch="<branch>"

指南

• 始终先解析 owner/repo；未提供时，从 git remote get-url origin 推断。
• 创建议题前始终检查标题是否重复。
• 删除标签前始终征求明确确认。
• 执行需要推送权限的工作流写入前，始终运行 safety-check。
• 编辑 .github/ISSUE_TEMPLATE/* 和 .github/workflows/* 时，始终使用文件工具。
• 绝不在议题／评论／模板／工作流正文中包含机密信息。
• 所有操作均返回包含 status、url 和 error 字段的结构化输出。

{
  "schema_version": "2.0",
  "id": "skill-system-github",
  "version": "1.0.0",
  "capabilities": ["github-issue", "github-label", "github-template", "github-workflow", "github-pr", "github-safety"],
  "effects": ["net.fetch", "proc.exec", "git.read", "fs.read", "fs.write"],
  "operations": {
    "manage-issues": {
      "description": "Create, list, comment on, close, or reopen GitHub issues with duplicate detection before create.",
      "input": {
        "action": { "type": "string", "required": true, "description": "One of: create, list, comment, close, reopen" },
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "title": { "type": "string", "required": false, "description": "Issue title for create" },
        "body": { "type": "string", "required": false, "description": "Issue body for create or comment body" },
        "number": { "type": "number", "required": false, "description": "Issue number for comment/close/reopen" },
        "state": { "type": "string", "required": false, "description": "Issue listing state: open, closed, all" },
        "limit": { "type": "number", "required": false, "description": "List limit" },
        "label": { "type": "string", "required": false, "description": "Optional label filter for listing" }
      },
      "output": {
        "description": "Operation status and issue URL when applicable.",
        "fields": { "status": "string", "url": "string", "error": "string" }
      },
      "entrypoints": {
        "agent": "scripts/manage-issues.md"
      }
    },
    "manage-labels": {
      "description": "Create, update, delete labels, and apply labels to issues in a GitHub repository.",
      "input": {
        "action": { "type": "string", "required": true, "description": "One of: create, update, delete, apply" },
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "name": { "type": "string", "required": false, "description": "Label name for create/update/delete" },
        "new_name": { "type": "string", "required": false, "description": "New label name for update" },
        "description": { "type": "string", "required": false, "description": "Label description for create/update" },
        "color": { "type": "string", "required": false, "description": "Hex color without #, for create/update" },
        "number": { "type": "number", "required": false, "description": "Issue number for apply" },
        "labels": { "type": "string", "required": false, "description": "Comma-separated labels for apply" },
        "confirm_delete": { "type": "boolean", "required": false, "description": "Explicit confirmation for delete" }
      },
      "output": {
        "description": "Operation status and optional resource URL.",
        "fields": { "status": "string", "url": "string", "error": "string" }
      },
      "entrypoints": {
        "agent": "scripts/manage-labels.md"
      }
    },
    "manage-templates": {
      "description": "Bootstrap and update repository issue templates under .github/ISSUE_TEMPLATE.",
      "input": {
        "action": { "type": "string", "required": true, "description": "One of: bootstrap, update" },
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "template_type": { "type": "string", "required": false, "description": "Template selector: bug_report, feature_request, config" },
        "content": { "type": "string", "required": false, "description": "Updated YAML content for update action" }
      },
      "output": {
        "description": "Operation status and changed path details.",
        "fields": { "status": "string", "url": "string", "error": "string" }
      },
      "entrypoints": {
        "agent": "scripts/manage-templates.md"
      }
    },
    "manage-workflows": {
      "description": "List or check workflow runs and create/update workflow YAML files safely.",
      "input": {
        "action": { "type": "string", "required": true, "description": "One of: list, check, create, update" },
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "workflow_name": { "type": "string", "required": false, "description": "Workflow display name or filename for check/update" },
        "workflow_file": { "type": "string", "required": false, "description": "Workflow filename under .github/workflows" },
        "content": { "type": "string", "required": false, "description": "Workflow YAML content for create/update" },
        "branch": { "type": "string", "required": false, "description": "Branch for API fallback updates" }
      },
      "output": {
        "description": "Operation status and workflow URL when available.",
        "fields": { "status": "string", "url": "string", "error": "string" }
      },
      "entrypoints": {
        "agent": "scripts/manage-workflows.md"
      }
    },
    "manage-prs": {
      "description": "List or create GitHub pull requests with branch safety checks.",
      "input": {
        "action": { "type": "string", "required": true, "description": "One of: list, create" },
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "title": { "type": "string", "required": false, "description": "PR title for create" },
        "body": { "type": "string", "required": false, "description": "PR body for create" },
        "base": { "type": "string", "required": false, "description": "Base branch" },
        "head": { "type": "string", "required": false, "description": "Head branch" },
        "limit": { "type": "number", "required": false, "description": "List limit" }
      },
      "output": {
        "description": "PR operation result",
        "fields": { "status": "string", "url": "string", "error": "string", "warnings": "array" }
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/github.py", "prs"],
        "agent": "Use scripts/github.py prs for list/create operations"
      }
    },
    "safety-check": {
      "description": "Check gh auth token scopes for workflow writes and choose push or gh api fallback path.",
      "input": {
        "repo": { "type": "string", "required": false, "description": "Target repo in owner/repo format" },
        "workflow_file": { "type": "string", "required": false, "description": "Workflow filename to write under .github/workflows" },
        "workflow_content": { "type": "string", "required": false, "description": "Workflow YAML content used for API fallback" },
        "branch": { "type": "string", "required": false, "description": "Target branch name" },
        "commit_message": { "type": "string", "required": false, "description": "Commit message for API fallback" }
      },
      "output": {
        "description": "Decision and recommended write path.",
        "fields": { "status": "string", "url": "string", "error": "string" }
      },
      "entrypoints": {
        "agent": "scripts/safety-check.md"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "Agent-executed operations; procedures are defined in markdown entrypoint scripts."
  }
}