aktonay/skillz / skills/ide-meta/permissioned-github
permissioned-github
UnverifiedGuidelines for interacting with GitHub and request permissions from the user when commands fail due to restrictions in the agent environment.
GitHub Skill
This skill describes how to interact with GitHub and request the permissions to perform actions that are not authorized by default in the agent environment. This skill is authoritative for the usage of the gh CLI and git command.
By default, the agent is restricted to performing only a subset of actions on GitHub.
How to Interact with GitHub
To perform actions on GitHub:
- Use the gh CLI. Always set the
-R ORG/REPOargument. - Do not use other commmands like curl.
- Do not write scripts to interact with the GitHub API servers directly.
To perform branch operations (e.g., push):
- Use the git command.
Asking for Permissions
Permission Format
The permission format is as follows:
<command-binary>.<action>(<resource_json>)
resource_json has the following fields:
- org: Mandatory GitHub organization. Use '*' to indicate all organizations.
- repo: Mandatory GitHub repository. Use '*' to indicate all repositories.
- pr: Optional pull request number. Use '*' to indicate all pull requests.
Supported actions:
- read: to view PR details, and to run
gh search prs. - create
- update: to comment, review, edit, close, reopen, etc.
- approve
- merge
- read: to view PR details, and to run
- issue: Optional issue number. Use '*' to indicate all issues.
Supported actions:
- read
- create
- update: to comment, review, edit, close, reopen, etc.
- branch: Mandatory branch name. Use '*' to indicate all branches.
Supported actions:
- read: to clone, pull, fetch, checkout, and to run
gh search commits. Always setbranchto*forread. - create: to push a new branch.
- update: to push to an existing remote branch (including force-push).
- delete: to delete a remote branch.
- read: to clone, pull, fetch, checkout, and to run
Other operations are not supported and the corresponding permission will not be granted. If you need support, stop immediately and tell the user you cannot proceed and why.
Examples
Example 1: Creating an Issue
Command: gh issue create --title "Bug report" --body "Description" -R myorg/myrepo
Permission: gh.create({"org": "myorg", "repo": "myrepo", "issue": "*"})
Note: keep the permission lean and don't populate empty fields
Example 2: Commenting on a PR
Command: gh pr comment 123 --body "Looks good" -R myorg/myrepo
Permission: gh.update({"org": "myorg", "repo": "myrepo", "pr": "123"})
Note: keep the permission lean and don't populate empty fields
Example 3: Closing an Issue
Command: gh issue close 123 --comment "closing issue" -R myorg/myrepo
Permission: gh.update({"org": "myorg", "repo": "myrepo", "issue": "123"})
Note: keep the permission lean and don't populate empty fields
Example 4: Approving a PR
Command: gh pr review 123 --approve --body "Looks good" -R myorg/myrepo
Permission: gh.approve({"org": "myorg", "repo": "myrepo", "pr": "123"})
Note: keep the permission lean and don't populate empty fields
Example 5: Pushing to an Existing Branch
Command: git push origin feature/my-feature (branch already exists on the remote)
Permission: git.update({"org": "myorg", "repo": "myrepo", "branch": "feature/my-feature"})
Note: use update for a force-push too; use create (below) when the branch does not yet exist on the remote.
Example 6: Creating a New Branch
Command: git push origin feature/my-feature (first push of a branch that does not exist on the remote)
Permission: git.create({"org": "myorg", "repo": "myrepo", "branch": "feature/my-feature"})
Example 7: Fetching all branches
Command: git fetch --all
Permission: git.read({"org": "myorg", "repo": "myrepo", "branch": "*"})
Note: read cannot be scoped to a single branch; branch must be *.
Example 8: Cloning a Repository
Command: git clone https://github.com/myorg/myrepo.git
Permission: git.read({"org": "myorg", "repo": "myrepo", "branch": "*"})
Example 9: Deleting a Branch
Command: git push origin --delete feature/my-feature
Permission: git.delete({"org": "myorg", "repo": "myrepo", "branch": "feature/my-feature"})
Note: keep the permission lean and don't populate empty fields
Example 10: Searching Pull Requests
Command: gh search prs -R myorg/myrepo --author alice
Permission: gh.read({"org": "myorg", "repo": "myrepo", "pr": "*"})
Note: for an organization-wide search, use --owner myorg in the command; the grant then uses repo: "*".
Example 11: Searching Commits
Command: gh search commits -R myorg/myrepo --author alice
Permission: git.read({"org": "myorg", "repo": "myrepo", "branch": "*"})
Note: commit search reuses the git read permission, so request a git.* grant, not a gh.* grant.
How and When to Ask for Permissions
You should only ask for permissions if the command failed. Each time you ask for a permission, it will prompt the user. Be mindful to only ask when you know the command fails to provide a good user experience.
When you have determined that you need permisison:
- Constuct the permission string as per previous section.
- Call the tool
ask_permission:
- Set Action="custom", Target=
- Do not set BypassSandbox.
- Run the original command that was denied.
Never try to pipe or redirect output of the gh command, it will not work in your environment
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |