skill-system-github

スキルシステム GitHub

gh を使用して一貫性のある GitHub 操作を実行します。ワークフローへの書き込みには明示的な安全性チェックを適用し、予測可能な戻り値の形式を使用します。

判断マトリクス

タスクの意図	操作	主要なバックエンド	備考
Issue の作成／一覧表示／コメント／クローズ／再オープン	manage-issues	gh issue	新しい Issue を作成する前に重複を確認します
ラベルの作成／更新／削除、Issue へのラベル適用	manage-labels	gh label、gh issue edit	削除を実行する前に確認します
プルリクエストの一覧表示／作成	manage-prs	gh pr	main/master への強制プッシュについて警告します
Issue テンプレートの初期設定／更新	manage-templates	ファイルの読み取り／書き込みツール	.github/ISSUE_TEMPLATE/* を直接編集します
ワークフローの一覧表示／確認／作成／更新	manage-workflows	gh workflow、ファイルの読み取り／書き込みツール	ワークフローの変更をプッシュする前に safety-check を実行します
トークンのスコープに基づくワークフローのプッシュ方法の判断	safety-check	gh auth status、gh api	workflow スコープがない場合は API による代替手段を使用します

コアパターン

パターン 1：リポジトリを解決して Issue 操作を実行する

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

パターン 2：ラベルのライフサイクルと Issue へのラベル適用

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 から推測します。
• Issue を作成する前に、必ずタイトルが重複していないか確認します。
• ラベルを削除する前に、必ず明示的な確認を求めます。
• プッシュ権限が必要なワークフローへの書き込み前に、必ず safety-check を実行します。
• .github/ISSUE_TEMPLATE/* と .github/workflows/* の編集には、必ずファイルツールを使用します。
• Issue／コメント／テンプレート／ワークフロー本文にシークレットを含めないでください。
• すべての操作について、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."
  }
}