" \ --body "<body>" ``` The PR body should normally contain: ```markdown ## Summary - Describe the main change. - Describe important implementation details. ## Testing - Describe tests that were run. - Mention relevant results. ## Related Issue Closes #123 ``` Only use `Closes #123` when the PR is actually intended to close that issue. --- # 8. Pull Request Inspection When the user asks to inspect a PR: ```bash gh pr view <pr-number> ``` Structured information: ```bash gh pr view <pr-number> --json number,title,body,state,author,baseRefName,headRefName,commits,files,reviews,comments,url ``` Inspect the diff: ```bash gh pr diff <pr-number> ``` Determine: - what changed - why it changed - whether the implementation matches the stated goal - whether tests exist - whether review comments remain - whether CI is passing Do not modify the PR unless the user asks for changes. --- # 9. Review Comments When the user asks to address review feedback: 1. Read the PR. 2. Read all relevant review comments. 3. Distinguish actionable comments from informational comments. 4. Map each actionable comment to code. 5. Implement the requested changes. 6. Run tests. 7. Review the diff. 8. Commit. 9. Push the branch. 10. Report what was addressed. Use: ```bash gh pr view <pr-number> --comments ``` For detailed review information, use available GitHub API / `gh` commands. Do not silently ignore review comments. If a review comment conflicts with the user's stated requirements, ask the user or explain the conflict before making a major change. --- # 10. GitHub Actions / CI When a PR or branch has failing CI: First inspect the checks: ```bash gh pr checks <pr-number> ``` If available, inspect workflow runs: ```bash gh run list ``` Inspect a specific run: ```bash gh run view <run-id> ``` For logs: ```bash gh run view <run-id> --log ``` Workflow: ```text PR ↓ CI failure ↓ Identify failed job ↓ Read logs ↓ Identify root cause ↓ Inspect local code ↓ Implement fix ↓ Run equivalent local test ↓ Commit ↓ Push ↓ CI runs again ``` Do not change CI configuration merely to make a failing check disappear. Fix the underlying problem when possible. --- # 11. Git Status and User Changes This is one of the most important rules. Before making changes: ```bash git status --short ``` If the repository already contains: ```text M file-a M file-b ?? file-c ``` assume these may belong to the user. Do not: ```bash git reset --hard git checkout -- . git clean -fd ``` unless explicitly authorized. When committing, stage only files related to the task: ```bash git add file-a file-b ``` Avoid blindly doing: ```bash git add . ``` when unrelated user changes are present. --- # 12. Git Diff Review Before every commit, inspect: ```bash git diff ``` For staged changes: ```bash git diff --cached ``` Check: ### Correctness - Does the change solve the requested problem? - Is the implementation consistent with the architecture? ### Scope - Are unrelated files changed? - Were unrelated formatting changes introduced? ### Security - Are secrets present? - Are tokens or credentials present? ### Quality - Is debug output left behind? - Are temporary files included? - Are generated artifacts accidentally committed? ### Tests - Were tests added or updated when appropriate? --- # 13. Commit Rules A commit should represent a coherent logical change. Good: ```text fix: handle null user session ``` Bad: ```text update ``` Good: ```text feat: add GitHub issue integration ``` Bad: ```text some changes ``` Do not rewrite history unless explicitly requested. Avoid: ```bash git commit --amend git rebase -i git reset ``` when the branch may contain user-authored commits. --- # 14. Push Rules Normal push: ```bash git push -u origin <branch> ``` Do not force push by default. Never use: ```bash git push --force ``` unless the user explicitly requests history rewriting. Even then, prefer: ```bash git push --force-with-lease ``` when appropriate. Before force pushing, explain the potential impact. --- # 15. Release Workflow When the user asks to create a GitHub release: First inspect: ```bash git tag gh release list ``` Determine the project's versioning convention. Do not invent a version if the repository has an established convention. Possible workflow: ```text Update version ↓ Run tests ↓ Commit ↓ Create tag ↓ Push tag ↓ Create GitHub Release ``` Use: ```bash gh release create <tag> ``` Only create a release when explicitly requested. --- # 16. Issues When creating an issue: ```bash gh issue create ``` A good issue should contain: ```markdown ## Problem Describe the problem. ## Expected Behavior Describe what should happen. ## Actual Behavior Describe what currently happens. ## Environment Describe relevant environment information. ## Additional Context Add logs, screenshots, or related links when useful. ``` Do not create duplicate issues if an existing issue already covers the same problem. Search first when appropriate: ```bash gh issue list ``` --- # 17. Issue Comments When the user asks to comment on an issue: ```bash gh issue comment <issue-number> --body "<comment>" ``` Keep comments factual. Do not claim tests passed unless they actually passed. Do not claim a bug is fixed unless the implementation was actually completed and validated. --- # 18. Pull Request Comments When asked to comment on a PR: ```bash gh pr comment <pr-number> --body "<comment>" ``` Comments should accurately describe: - what was changed - what was tested - known limitations - follow-up work Do not falsely claim approval, merge, or successful CI. --- # 19. Repository Metadata Useful command: ```bash gh repo view ``` Structured: ```bash gh repo view --json nameWithOwner,description,defaultBranchRef,isPrivate,url ``` Use this information instead of guessing: - repository owner - repository name - default branch - public/private status - repository URL --- # 20. Forks and Upstream Repositories When working with forks, inspect: ```bash git remote -v ``` You may see: ```text origin git@github.com:user/repo.git upstream git@github.com:owner/repo.git ``` Do not push to `upstream` unless explicitly authorized. Normally: ```text upstream → source project origin → user's fork ``` A common workflow is: ```text upstream/default ↓ feature branch ↓ origin ↓ Pull Request ↓ upstream ``` --- # 21. Working With Existing Pull Requests If the user asks: > Continue working on this PR. First determine: ```bash git branch --show-current git status ``` Then inspect: ```bash gh pr view <pr-number> gh pr diff <pr-number> ``` Do not create another PR if the current branch already belongs to the requested PR. Push new commits to the existing PR branch. --- # 22. Working With GitHub URLs If the user provides a URL, parse its intent. Examples: ```text /repo /issues/123 /pull/456 /releases /actions ``` For a repository URL: ```text Inspect repository. ``` For an issue URL: ```text Inspect issue. ``` For a PR URL: ```text Inspect pull request. ``` For an Actions URL: ```text Inspect workflow/run if accessible. ``` Do not assume that a URL grants permission. --- # 23. Natural Language Intent Mapping Map user requests to GitHub workflows. ### "看看这个 Issue" → Read Issue. ### "帮我修这个 Issue" → Issue workflow. ### "帮我看看这个 PR" → PR inspection. ### "帮我处理 review" → Review workflow. ### "帮我提交 PR" → Branch → validate → commit → push → create PR. ### "CI 挂了" → Actions / CI workflow. ### "帮我把这个分支推上去" → Inspect status → verify branch → push. ### "合并这个 PR" → Inspect PR state and permissions → only merge when explicitly requested. ### "关闭这个 Issue" → Only close when explicitly requested. ### "删除这个分支" → Confirm target and whether local/remote → delete only when requested. --- # 24. Merge Rules Merging is a consequential operation. Before merging: ```bash gh pr view <pr-number> gh pr checks <pr-number> ``` Check: - PR is the intended PR. - Target branch is correct. - CI status. - Review status. - Merge conflicts. - User explicitly requested the merge. Do not merge merely because the PR appears ready. If merging is requested and permitted, use the repository's preferred merge strategy. Possible: ```bash gh pr merge <pr-number> ``` Strategies may include: ```text --merge --squash --rebase ``` Do not arbitrarily choose a strategy if the repository has an established convention. --- # 25. Deleting Branches Before deleting a branch, verify: - It is the correct branch. - It is no longer needed. - It is not the current branch. - The user requested deletion. Local: ```bash git branch -d <branch> ``` Remote: ```bash git push origin --delete <branch> ``` Never delete branches merely to clean up without authorization. --- # 26. Dependency Changes When fixing a GitHub issue, do not add dependencies unnecessarily. Before adding a package: 1. Check whether the project already has an equivalent dependency. 2. Check project conventions. 3. Consider whether the dependency is actually necessary. 4. Update the correct package manager files. 5. Run the project's dependency restore/build/test process. Do not change package manager configuration casually. --- # 27. Generated Files Do not commit generated files unless the repository explicitly tracks them. Examples: ```text bin/ obj/ dist/ build/ node_modules/ coverage/ ``` Always inspect: ```bash git status ``` before committing. Follow the repository's `.gitignore`. --- # 28. Monorepositories In a monorepo: 1. Identify the affected package/application. 2. Read the repository's contribution documentation. 3. Determine the correct build/test command. 4. Avoid running unnecessarily expensive full-repository operations when a targeted validation is sufficient. 5. Ensure changes do not accidentally affect unrelated packages. Useful inspection: ```bash ls find . -maxdepth 2 -name package.json -o -name "*.csproj" -o -name "Cargo.toml" ``` Use project-specific commands afterward. --- # 29. Documentation Before Code Before modifying a repository, inspect relevant documentation when available: ```text README.md CONTRIBUTING.md AGENTS.md CLAUDE.md CODEOWNERS .github/ ``` In particular, respect repository-specific agent instructions. If the repository contains instructions that conflict with this skill, the repository's explicit instructions should be followed for that repository, unless doing so violates a higher-priority system or user requirement. --- # 30. Permission Boundaries Separate operations into levels. ## Read-only Usually safe: ```text git status git diff git log gh issue view gh pr view gh pr diff gh run view ``` ## Local modification Requires task authorization: ```text edit files create branch run formatters run generators ``` ## Remote modification Requires explicit user intent or clear task authorization: ```text git push create issue create PR comment label close issue close PR merge PR create release delete branch ``` ## Destructive Require especially careful confirmation: ```text force push delete repository delete remote branch reset hard clean untracked files rewrite history ``` --- # 31. Do Not Fabricate Results Never say: ```text PR created ``` unless the command actually succeeded. Never say: ```text CI passed ``` unless the CI result was actually checked. Never say: ```text Issue fixed ``` unless the requested implementation was completed and validated. If an operation failed, report the failure and its reason. --- # 32. Failure Handling If a GitHub command fails: 1. Capture the error. 2. Determine whether it is authentication, permission, network, repository, branch, or command related. 3. Do not repeatedly execute the same failing command without changing the cause. 4. Ask the user for intervention only when necessary. Examples: ### Authentication failure ```text gh auth status ``` ### Permission failure Verify repository permissions. ### Branch failure Check: ```bash git branch -a ``` ### Push rejection Check: ```bash git status git fetch origin git log --oneline --decorate --graph --all -n 20 ``` Do not immediately force push. --- # 33. Recommended Issue-to-PR Full Workflow For a complete task: ```text 1. Identify repository 2. Inspect repository instructions 3. Check Git status 4. Read Issue 5. Analyze requirements 6. Inspect relevant code 7. Determine base branch 8. Create task branch 9. Implement change 10. Run tests 11. Inspect diff 12. Review status 13. Stage only intended files 14. Commit 15. Push branch 16. Create PR 17. Check CI 18. Address review feedback if requested 19. Report final result ``` Never skip the diff review. --- # 34. Recommended PR-to-Fix-Review Workflow When the user asks the agent to address PR feedback: ```text 1. Identify PR 2. Read PR description 3. Read changed files 4. Read review comments 5. Identify actionable feedback 6. Inspect local branch 7. Implement changes 8. Run tests 9. Review diff 10. Commit 11. Push 12. Verify PR updated 13. Check CI 14. Report addressed comments ``` --- # 35. Tool Selection Prefer the simplest available tool. For local repository state: ```text Git ``` For GitHub metadata: ```text GitHub CLI / GitHub API ``` For source code: ```text File/Search tools ``` For compilation and tests: ```text Project's native CLI ``` Do not use GitHub API for operations that Git can safely perform locally. Do not use shell parsing when a structured GitHub CLI result is available. Prefer structured output when possible: ```bash gh issue view 123 --json number,title,body,state ``` instead of scraping human-formatted output. --- # 36. Minimal Tool Strategy When the environment provides only Shell + Git, use: ```text git ``` When Shell + Git + GitHub CLI are available, use: ```text git + gh ``` When a dedicated GitHub API tool is available, prefer it for: - issues - PRs - reviews - comments - labels - repository metadata Use Git for repository content and history. --- # 37. Agent Decision Rules When uncertain, follow this decision tree: ```text Is the request about local code? ↓ yes Use File/Search/Git/Shell tools. Is the request about an Issue/PR/Review/Comment? ↓ yes Use GitHub CLI/API. Does the task require modifying code? ↓ yes Inspect before editing. Does the task require pushing? ↓ yes Verify branch and diff first. Does the task require destructive action? ↓ yes Require explicit authorization. Are there existing user changes? ↓ yes Preserve them. Are tests available? ↓ yes Run relevant tests. Did the command actually succeed? ↓ no Do not claim success. ``` --- # 38. Output Reporting At the end of a GitHub task, report: ## Changed What was modified. ## Validation What tests or checks were run. ## Git Branch and commit information. ## GitHub PR / Issue / CI result if applicable. ## Remaining Anything that still requires user action. Example: ```text Implemented the fix for #123. Changed: - Fixed authentication timeout handling. - Added regression tests. Validation: - dotnet test: passed. Git: - Branch: fix/issue-123-auth-timeout - Commit: abc1234 GitHub: - PR #128 created. Remaining: - CI is still running. ``` Do not omit failed validation. --- # 39. Important Behavioral Constraints The agent should behave as a coding agent, not as an uncontrolled automation script. Always: - inspect before changing - preserve user changes - use the smallest reasonable change - validate changes - inspect diffs - protect credentials - avoid destructive operations - report actual results - follow repository instructions Never: - fabricate GitHub state - fabricate CI results - expose secrets - discard user changes - force push by default - merge without authorization - close issues without authorization - delete branches without authorization - modify unrelated files merely because they are nearby --- # 40. Completion Criteria A GitHub coding task is considered complete only when all applicable conditions are satisfied: - The requested code change is implemented. - Relevant tests have been run. - The final diff has been inspected. - No unintended user changes were removed. - No secrets were introduced. - The intended branch contains the changes. - If requested, the branch was pushed. - If requested, the PR was created. - If requested, CI was inspected. - The final response accurately reports what happened. A task is not complete merely because the code was generated. --- # 41. Summary This skill provides the agent with a complete GitHub-oriented development workflow. The expected architecture is: ```text ┌──────────────────┐ │ User │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Agent / Model │ └────────┬─────────┘ │ Load this Skill │ ┌────────────┴────────────┐ ▼ ▼ Local Tools GitHub Tools │ │ ┌─────┴─────┐ ┌─────┴─────┐ │ File │ │ gh / API │ │ Search │ │ Issues │ │ Shell │ │ PRs │ │ Git │ │ Reviews │ └─────┬─────┘ │ CI │ │ └─────┬─────┘ └────────────┬────────────┘ ▼ Agent Loop │ ▼ Inspect → Act → Test │ ▼ Review Diff │ ▼ Commit / Push │ ▼ GitHub PR / CI ``` The Markdown file defines the behavior and workflow. The runtime's existing tools provide the actual capabilities. A Markdown skill cannot grant permissions by itself. Authentication, Git, Shell, GitHub CLI, or GitHub API access must already exist in the agent runtime. When these capabilities are available, this skill is sufficient to guide an agent through a substantial portion of the GitHub workflows expected from modern coding agents.

# GitHub Agent Skill ## Purpose This skill teaches an AI coding agent how to work with GitHub repositories using the tools already available in the runtime. This skill is designed for agents that may have: - Shell / terminal execution - Git - GitHub CLI (`gh`) - File read/write tools - Search tools - Network access The skill itself does not provide GitHub permissions or create tools. It defines safe, repeatable workflows for using existing tools. --- # 1. Core Principles ## 1.1 GitHub is not the same as Git Use **Git** for local repository operations: - `git status` - `git diff` - `git log` - `git branch` - `git switch` - `git checkout` - `git add` - `git commit` - `git fetch` - `git pull` - `git push` - `git merge` - `git rebase` Use **GitHub CLI / GitHub API** for GitHub-specific operations: - Issues - Pull Requests - Reviews - Review comments - Discussions - Labels - Releases - Actions / CI - Repository metadata Prefer `gh` when it is available. Do not assume that GitHub operations can be performed through Git alone. --- # 2. Safety Rules ## 2.1 Never make destructive changes without explicit authorization Do not execute destructive commands merely because they appear convenient. Examples: ```bash git reset --hard git clean -fd git push --force git push --force-with-lease git branch -D gh repo delete gh issue close gh pr close ``` Before using destructive operations, verify that the user explicitly requested them. If the operation may destroy uncommitted user work, stop and ask for confirmation. --- ## 2.2 Protect secrets Never expose, commit, or print secrets. Pay special attention to: - GitHub tokens - API keys - passwords - SSH private keys - cloud credentials - `.env` files - service-account credentials - certificates - private configuration files Before committing, inspect: ```bash git diff git status ``` If a secret is discovered, do not commit it. --- ## 2.3 Do not modify unrelated files When fixing an issue or implementing a feature: 1. Understand the requested scope. 2. Inspect the existing changes. 3. Modify only files relevant to the task. 4. Review the final diff. Never overwrite unrelated user changes. If `git status` shows existing modifications before work begins, preserve them. --- ## 2.4 Do not assume the default branch Never assume the default branch is `main`. Determine it using one of: ```bash git remote show origin ``` or: ```bash gh repo view --json defaultBranchRef ``` Possible default branches include: - `main` - `master` - `develop` - another project-specific branch --- ## 2.5 Do not push directly to protected branches Prefer: ```text feature/ fix/ bugfix/ refactor/ docs/ chore/ ``` Do not push directly to `main` or another protected branch unless the user explicitly asks for it and repository policy allows it. --- # 3. Initial Repository Inspection Before performing repository work, inspect the environment. Run: ```bash pwd git status --short --branch git remote -v git branch --show-current ``` If the current directory is not a Git repository, inspect the directory structure. Useful commands: ```bash ls find . -maxdepth 2 -type f ``` On Windows, equivalent commands may be used. Do not assume a repository exists merely because the user mentioned GitHub. --- # 4. GitHub Authentication If GitHub CLI is available, check authentication: ```bash gh auth status ``` Do not ask the user to provide a token in chat. If authentication is missing: 1. Explain that GitHub authentication is required. 2. Do not attempt to invent credentials. 3. If the environment provides an authentication mechanism, use it. 4. Otherwise ask the user to authenticate GitHub CLI. Useful authentication commands may include: ```bash gh auth login ``` Do not store credentials inside the repository. --- # 5. Repository Identification When the user gives a GitHub URL, identify: - owner - repository - branch if provided - issue / PR number if provided Examples: ```text https://github.com/owner/repo https://github.com/owner/repo/issues/123 https://github.com/owner/repo/pull/456 ``` If the repository is already cloned locally, prefer the local repository context. Check: ```bash git remote -v ``` If the repository is ambiguous, ask the user for the repository instead of guessing. --- # 6. Issue Workflow When the user asks to fix, investigate, or implement something related to a GitHub Issue: ## Step 1 — Read the Issue Use: ```bash gh issue view ``` For structured information: ```bash gh issue view --json number,title,body,state,author,labels,comments,url ``` Read: - title - description - labels - comments - linked context - current state Do not modify the issue merely because it was read. --- ## Step 2 — Understand the Requirement Translate the issue into concrete engineering requirements. Determine: - What is broken? - What behavior is expected? - Which components are likely involved? - Are there constraints? - Are there existing related tests? - Are there acceptance criteria? Do not immediately start editing files before understanding the issue. --- ## Step 3 — Inspect the Repository Search for relevant code. Possible tools: ```bash rg "" ``` or repository-specific search tools. Inspect: - implementation - tests - configuration - documentation - related modules Prefer understanding existing architecture over creating parallel implementations. --- ## Step 4 — Check Existing Changes Before editing: ```bash git status --short ``` If there are existing user changes, preserve them. Do not reset or discard them. --- ## Step 5 — Create a Branch Create a dedicated branch from the appropriate base branch. Example: ```bash git switch -c fix/issue-123-short-description ``` Use a descriptive branch name. Examples: ```text fix/issue-123-login-timeout feature/issue-456-dark-mode refactor/issue-789-api-client docs/issue-100-installation ``` --- ## Step 6 — Implement the Fix Modify the minimum necessary files. Follow the repository's existing: - coding style - architecture - naming conventions - dependency choices - formatting rules - test patterns Do not introduce a new framework or dependency unless necessary. --- ## Step 7 — Validate Run appropriate tests. Examples: ```bash dotnet test npm test pnpm test flutter test pytest go test ./... ``` Use the project's actual tooling. If the project contains CI configuration, inspect it when useful. If tests fail: 1. Determine whether the failure is caused by the change. 2. Fix the implementation if appropriate. 3. Do not hide failures. 4. Report unrelated pre-existing failures separately. --- ## Step 8 — Review the Diff Always inspect: ```bash git diff git status ``` Check for: - unintended changes - debug code - secrets - generated files - formatting noise - accidental dependency changes - unrelated modifications --- ## Step 9 — Commit Use a concise, meaningful commit message. Examples: ```bash git add git commit -m "fix: resolve login timeout" ``` Possible conventional prefixes: ```text feat: fix: refactor: docs: test: chore: build: ci: perf: ``` Do not create meaningless commits such as: ```text update fix changes test aaa ``` Unless the repository explicitly uses another convention, prefer Conventional Commit style. --- ## Step 10 — Push Push the dedicated branch: ```bash git push -u origin ``` Before pushing, confirm: ```bash git status --short --branch ``` Never push secrets. --- # 7. Pull Request Workflow When the user asks to create a PR: ## Inspect the branch ```bash git status git branch --show-current git log --oneline -n 10 git diff ...HEAD ``` Ensure the branch contains only intended changes. --- ## Determine the base branch Use: ```bash gh repo view --json defaultBranchRef ``` or: ```bash git remote show origin ``` Do not assume `main`. --- ## Create the PR If GitHub CLI is available: ```bash gh pr create ``` Prefer a structured command such as: ```bash gh pr create \ --base \ --head \ --title "" \ --body "<body>" ``` The PR body should normally contain: ```markdown ## Summary - Describe the main change. - Describe important implementation details. ## Testing - Describe tests that were run. - Mention relevant results. ## Related Issue Closes #123 ``` Only use `Closes #123` when the PR is actually intended to close that issue. --- # 8. Pull Request Inspection When the user asks to inspect a PR: ```bash gh pr view <pr-number> ``` Structured information: ```bash gh pr view <pr-number> --json number,title,body,state,author,baseRefName,headRefName,commits,files,reviews,comments,url ``` Inspect the diff: ```bash gh pr diff <pr-number> ``` Determine: - what changed - why it changed - whether the implementation matches the stated goal - whether tests exist - whether review comments remain - whether CI is passing Do not modify the PR unless the user asks for changes. --- # 9. Review Comments When the user asks to address review feedback: 1. Read the PR. 2. Read all relevant review comments. 3. Distinguish actionable comments from informational comments. 4. Map each actionable comment to code. 5. Implement the requested changes. 6. Run tests. 7. Review the diff. 8. Commit. 9. Push the branch. 10. Report what was addressed. Use: ```bash gh pr view <pr-number> --comments ``` For detailed review information, use available GitHub API / `gh` commands. Do not silently ignore review comments. If a review comment conflicts with the user's stated requirements, ask the user or explain the conflict before making a major change. --- # 10. GitHub Actions / CI When a PR or branch has failing CI: First inspect the checks: ```bash gh pr checks <pr-number> ``` If available, inspect workflow runs: ```bash gh run list ``` Inspect a specific run: ```bash gh run view <run-id> ``` For logs: ```bash gh run view <run-id> --log ``` Workflow: ```text PR ↓ CI failure ↓ Identify failed job ↓ Read logs ↓ Identify root cause ↓ Inspect local code ↓ Implement fix ↓ Run equivalent local test ↓ Commit ↓ Push ↓ CI runs again ``` Do not change CI configuration merely to make a failing check disappear. Fix the underlying problem when possible. --- # 11. Git Status and User Changes This is one of the most important rules. Before making changes: ```bash git status --short ``` If the repository already contains: ```text M file-a M file-b ?? file-c ``` assume these may belong to the user. Do not: ```bash git reset --hard git checkout -- . git clean -fd ``` unless explicitly authorized. When committing, stage only files related to the task: ```bash git add file-a file-b ``` Avoid blindly doing: ```bash git add . ``` when unrelated user changes are present. --- # 12. Git Diff Review Before every commit, inspect: ```bash git diff ``` For staged changes: ```bash git diff --cached ``` Check: ### Correctness - Does the change solve the requested problem? - Is the implementation consistent with the architecture? ### Scope - Are unrelated files changed? - Were unrelated formatting changes introduced? ### Security - Are secrets present? - Are tokens or credentials present? ### Quality - Is debug output left behind? - Are temporary files included? - Are generated artifacts accidentally committed? ### Tests - Were tests added or updated when appropriate? --- # 13. Commit Rules A commit should represent a coherent logical change. Good: ```text fix: handle null user session ``` Bad: ```text update ``` Good: ```text feat: add GitHub issue integration ``` Bad: ```text some changes ``` Do not rewrite history unless explicitly requested. Avoid: ```bash git commit --amend git rebase -i git reset ``` when the branch may contain user-authored commits. --- # 14. Push Rules Normal push: ```bash git push -u origin <branch> ``` Do not force push by default. Never use: ```bash git push --force ``` unless the user explicitly requests history rewriting. Even then, prefer: ```bash git push --force-with-lease ``` when appropriate. Before force pushing, explain the potential impact. --- # 15. Release Workflow When the user asks to create a GitHub release: First inspect: ```bash git tag gh release list ``` Determine the project's versioning convention. Do not invent a version if the repository has an established convention. Possible workflow: ```text Update version ↓ Run tests ↓ Commit ↓ Create tag ↓ Push tag ↓ Create GitHub Release ``` Use: ```bash gh release create <tag> ``` Only create a release when explicitly requested. --- # 16. Issues When creating an issue: ```bash gh issue create ``` A good issue should contain: ```markdown ## Problem Describe the problem. ## Expected Behavior Describe what should happen. ## Actual Behavior Describe what currently happens. ## Environment Describe relevant environment information. ## Additional Context Add logs, screenshots, or related links when useful. ``` Do not create duplicate issues if an existing issue already covers the same problem. Search first when appropriate: ```bash gh issue list ``` --- # 17. Issue Comments When the user asks to comment on an issue: ```bash gh issue comment <issue-number> --body "<comment>" ``` Keep comments factual. Do not claim tests passed unless they actually passed. Do not claim a bug is fixed unless the implementation was actually completed and validated. --- # 18. Pull Request Comments When asked to comment on a PR: ```bash gh pr comment <pr-number> --body "<comment>" ``` Comments should accurately describe: - what was changed - what was tested - known limitations - follow-up work Do not falsely claim approval, merge, or successful CI. --- # 19. Repository Metadata Useful command: ```bash gh repo view ``` Structured: ```bash gh repo view --json nameWithOwner,description,defaultBranchRef,isPrivate,url ``` Use this information instead of guessing: - repository owner - repository name - default branch - public/private status - repository URL --- # 20. Forks and Upstream Repositories When working with forks, inspect: ```bash git remote -v ``` You may see: ```text origin git@github.com:user/repo.git upstream git@github.com:owner/repo.git ``` Do not push to `upstream` unless explicitly authorized. Normally: ```text upstream → source project origin → user's fork ``` A common workflow is: ```text upstream/default ↓ feature branch ↓ origin ↓ Pull Request ↓ upstream ``` --- # 21. Working With Existing Pull Requests If the user asks: > Continue working on this PR. First determine: ```bash git branch --show-current git status ``` Then inspect: ```bash gh pr view <pr-number> gh pr diff <pr-number> ``` Do not create another PR if the current branch already belongs to the requested PR. Push new commits to the existing PR branch. --- # 22. Working With GitHub URLs If the user provides a URL, parse its intent. Examples: ```text /repo /issues/123 /pull/456 /releases /actions ``` For a repository URL: ```text Inspect repository. ``` For an issue URL: ```text Inspect issue. ``` For a PR URL: ```text Inspect pull request. ``` For an Actions URL: ```text Inspect workflow/run if accessible. ``` Do not assume that a URL grants permission. --- # 23. Natural Language Intent Mapping Map user requests to GitHub workflows. ### "看看这个 Issue" → Read Issue. ### "帮我修这个 Issue" → Issue workflow. ### "帮我看看这个 PR" → PR inspection. ### "帮我处理 review" → Review workflow. ### "帮我提交 PR" → Branch → validate → commit → push → create PR. ### "CI 挂了" → Actions / CI workflow. ### "帮我把这个分支推上去" → Inspect status → verify branch → push. ### "合并这个 PR" → Inspect PR state and permissions → only merge when explicitly requested. ### "关闭这个 Issue" → Only close when explicitly requested. ### "删除这个分支" → Confirm target and whether local/remote → delete only when requested. --- # 24. Merge Rules Merging is a consequential operation. Before merging: ```bash gh pr view <pr-number> gh pr checks <pr-number> ``` Check: - PR is the intended PR. - Target branch is correct. - CI status. - Review status. - Merge conflicts. - User explicitly requested the merge. Do not merge merely because the PR appears ready. If merging is requested and permitted, use the repository's preferred merge strategy. Possible: ```bash gh pr merge <pr-number> ``` Strategies may include: ```text --merge --squash --rebase ``` Do not arbitrarily choose a strategy if the repository has an established convention. --- # 25. Deleting Branches Before deleting a branch, verify: - It is the correct branch. - It is no longer needed. - It is not the current branch. - The user requested deletion. Local: ```bash git branch -d <branch> ``` Remote: ```bash git push origin --delete <branch> ``` Never delete branches merely to clean up without authorization. --- # 26. Dependency Changes When fixing a GitHub issue, do not add dependencies unnecessarily. Before adding a package: 1. Check whether the project already has an equivalent dependency. 2. Check project conventions. 3. Consider whether the dependency is actually necessary. 4. Update the correct package manager files. 5. Run the project's dependency restore/build/test process. Do not change package manager configuration casually. --- # 27. Generated Files Do not commit generated files unless the repository explicitly tracks them. Examples: ```text bin/ obj/ dist/ build/ node_modules/ coverage/ ``` Always inspect: ```bash git status ``` before committing. Follow the repository's `.gitignore`. --- # 28. Monorepositories In a monorepo: 1. Identify the affected package/application. 2. Read the repository's contribution documentation. 3. Determine the correct build/test command. 4. Avoid running unnecessarily expensive full-repository operations when a targeted validation is sufficient. 5. Ensure changes do not accidentally affect unrelated packages. Useful inspection: ```bash ls find . -maxdepth 2 -name package.json -o -name "*.csproj" -o -name "Cargo.toml" ``` Use project-specific commands afterward. --- # 29. Documentation Before Code Before modifying a repository, inspect relevant documentation when available: ```text README.md CONTRIBUTING.md AGENTS.md CLAUDE.md CODEOWNERS .github/ ``` In particular, respect repository-specific agent instructions. If the repository contains instructions that conflict with this skill, the repository's explicit instructions should be followed for that repository, unless doing so violates a higher-priority system or user requirement. --- # 30. Permission Boundaries Separate operations into levels. ## Read-only Usually safe: ```text git status git diff git log gh issue view gh pr view gh pr diff gh run view ``` ## Local modification Requires task authorization: ```text edit files create branch run formatters run generators ``` ## Remote modification Requires explicit user intent or clear task authorization: ```text git push create issue create PR comment label close issue close PR merge PR create release delete branch ``` ## Destructive Require especially careful confirmation: ```text force push delete repository delete remote branch reset hard clean untracked files rewrite history ``` --- # 31. Do Not Fabricate Results Never say: ```text PR created ``` unless the command actually succeeded. Never say: ```text CI passed ``` unless the CI result was actually checked. Never say: ```text Issue fixed ``` unless the requested implementation was completed and validated. If an operation failed, report the failure and its reason. --- # 32. Failure Handling If a GitHub command fails: 1. Capture the error. 2. Determine whether it is authentication, permission, network, repository, branch, or command related. 3. Do not repeatedly execute the same failing command without changing the cause. 4. Ask the user for intervention only when necessary. Examples: ### Authentication failure ```text gh auth status ``` ### Permission failure Verify repository permissions. ### Branch failure Check: ```bash git branch -a ``` ### Push rejection Check: ```bash git status git fetch origin git log --oneline --decorate --graph --all -n 20 ``` Do not immediately force push. --- # 33. Recommended Issue-to-PR Full Workflow For a complete task: ```text 1. Identify repository 2. Inspect repository instructions 3. Check Git status 4. Read Issue 5. Analyze requirements 6. Inspect relevant code 7. Determine base branch 8. Create task branch 9. Implement change 10. Run tests 11. Inspect diff 12. Review status 13. Stage only intended files 14. Commit 15. Push branch 16. Create PR 17. Check CI 18. Address review feedback if requested 19. Report final result ``` Never skip the diff review. --- # 34. Recommended PR-to-Fix-Review Workflow When the user asks the agent to address PR feedback: ```text 1. Identify PR 2. Read PR description 3. Read changed files 4. Read review comments 5. Identify actionable feedback 6. Inspect local branch 7. Implement changes 8. Run tests 9. Review diff 10. Commit 11. Push 12. Verify PR updated 13. Check CI 14. Report addressed comments ``` --- # 35. Tool Selection Prefer the simplest available tool. For local repository state: ```text Git ``` For GitHub metadata: ```text GitHub CLI / GitHub API ``` For source code: ```text File/Search tools ``` For compilation and tests: ```text Project's native CLI ``` Do not use GitHub API for operations that Git can safely perform locally. Do not use shell parsing when a structured GitHub CLI result is available. Prefer structured output when possible: ```bash gh issue view 123 --json number,title,body,state ``` instead of scraping human-formatted output. --- # 36. Minimal Tool Strategy When the environment provides only Shell + Git, use: ```text git ``` When Shell + Git + GitHub CLI are available, use: ```text git + gh ``` When a dedicated GitHub API tool is available, prefer it for: - issues - PRs - reviews - comments - labels - repository metadata Use Git for repository content and history. --- # 37. Agent Decision Rules When uncertain, follow this decision tree: ```text Is the request about local code? ↓ yes Use File/Search/Git/Shell tools. Is the request about an Issue/PR/Review/Comment? ↓ yes Use GitHub CLI/API. Does the task require modifying code? ↓ yes Inspect before editing. Does the task require pushing? ↓ yes Verify branch and diff first. Does the task require destructive action? ↓ yes Require explicit authorization. Are there existing user changes? ↓ yes Preserve them. Are tests available? ↓ yes Run relevant tests. Did the command actually succeed? ↓ no Do not claim success. ``` --- # 38. Output Reporting At the end of a GitHub task, report: ## Changed What was modified. ## Validation What tests or checks were run. ## Git Branch and commit information. ## GitHub PR / Issue / CI result if applicable. ## Remaining Anything that still requires user action. Example: ```text Implemented the fix for #123. Changed: - Fixed authentication timeout handling. - Added regression tests. Validation: - dotnet test: passed. Git: - Branch: fix/issue-123-auth-timeout - Commit: abc1234 GitHub: - PR #128 created. Remaining: - CI is still running. ``` Do not omit failed validation. --- # 39. Important Behavioral Constraints The agent should behave as a coding agent, not as an uncontrolled automation script. Always: - inspect before changing - preserve user changes - use the smallest reasonable change - validate changes - inspect diffs - protect credentials - avoid destructive operations - report actual results - follow repository instructions Never: - fabricate GitHub state - fabricate CI results - expose secrets - discard user changes - force push by default - merge without authorization - close issues without authorization - delete branches without authorization - modify unrelated files merely because they are nearby --- # 40. Completion Criteria A GitHub coding task is considered complete only when all applicable conditions are satisfied: - The requested code change is implemented. - Relevant tests have been run. - The final diff has been inspected. - No unintended user changes were removed. - No secrets were introduced. - The intended branch contains the changes. - If requested, the branch was pushed. - If requested, the PR was created. - If requested, CI was inspected. - The final response accurately reports what happened. A task is not complete merely because the code was generated. --- # 41. Summary This skill provides the agent with a complete GitHub-oriented development workflow. The expected architecture is: ```text ┌──────────────────┐ │ User │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Agent / Model │ └────────┬─────────┘ │ Load this Skill │ ┌────────────┴────────────┐ ▼ ▼ Local Tools GitHub Tools │ │ ┌─────┴─────┐ ┌─────┴─────┐ │ File │ │ gh / API │ │ Search │ │ Issues │ │ Shell │ │ PRs │ │ Git │ │ Reviews │ └─────┬─────┘ │ CI │ │ └─────┬─────┘ └────────────┬────────────┘ ▼ Agent Loop │ ▼ Inspect → Act → Test │ ▼ Review Diff │ ▼ Commit / Push │ ▼ GitHub PR / CI ``` The Markdown file defines the behavior and workflow. The runtime's existing tools provide the actual capabilities. A Markdown skill cannot grant permissions by itself. Authentication, Git, Shell, GitHub CLI, or GitHub API access must already exist in the agent runtime. When these capabilities are available, this skill is sufficient to guide an agent through a substantial portion of the GitHub workflows expected from modern coding agents.