agentleFS
NVIDIAKnown publisherNVIDIA/nemoclaw-community/examples/recipes/nvidia/developer-community-chief-of-staff/agents/hermes/skills/github-readonly-live/SKILL.md

github-readonly-live

Skill142 starsChanged 3 months agoApache-2.0View on GitHub

Read an allowed live GitHub repository through authenticated, policy-scoped GitHub REST GET requests.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. About 0 are common, 7 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Use this skill for current live GitHub REST data from a repository allowed by the sandbox policy.

    line 8
  2. Distinctive:

    Read current issues, issue comments, pull requests, pull request files, reviews, commits, branches, labels, milestones, README, or …

    line 14
  3. Distinctive:

    Check live state when the source ETL mirror may be stale or empty.

    line 17
  4. Very specific:

    Do not use this skill for GitHub discussions or NVIDIA forums.

    line 19
  5. Distinctive:

    Treat it as a secret placeholder: do not print it, modify it, or copy it into responses.

    line 30
  6. Very specific:

    Do not run env, printenv, echo, or similar commands against GITHUB_TOKEN.

    line 32
  7. Very specific:

    Do not inspect .env files, shell environments, proxy settings, or token variables to troubleshoot GitHub.

    line 34
  8. Very specific:

    Only repository-scoped GET requests to api.github.com are allowed.

    line 37
  9. Very specific:

    Do not use gh, git, github.com, raw.githubusercontent.com, codeload.github.com, GraphQL, or GitHub search endpoints.

    line 38
  10. Distinctive:

    If a request returns an OpenShell policy 403, report the policy scope instead of trying another GitHub host, another binary, or a …

    line 40
  11. Distinctive:

    If explicitly asked to validate that a write is blocked, do not inspect the token variable.

    line 42
  12. Very specific:

    Always run the bundled helper script via the terminal tool.

    line 65
  13. Very specific:

    Do not invoke github-readonly-live as a shell command.

    line 70
  14. Very specific:

    Do not search for GitHub binaries with which, command -v, ls /usr/bin, or similar commands.

    line 73
  15. Very specific:

    Use repository-relative REST routes only: ., issues, issues/<number>, issues/<number>/comments, pulls, pulls/<number>, …

    line 98
  16. Very specific:

    Put query strings in --param KEY=VALUE, not in the route.

    line 101
  17. Very specific:

    Use --paginate --count for exact counts.

    line 102
  18. Very specific:

    Use --fields to keep output small instead of piping to python -c, jq, or custom scripts.

    line 104
  19. Very specific:

    Use --exclude-pulls on the issues route when the user asks for issues rather than PRs, because GitHub's issues endpoint includes pull …

    line 106
  20. Distinctive:

    Do not merge their results without naming which source each fact came from.

    line 123
  21. Very specific:

    If the helper is rate-limited, report that GitHub auth was absent or exhausted.

    line 124

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

github-readonly-live

Use this skill for current live GitHub REST data from a repository allowed by the sandbox policy.

When to use

  • Inspect a currently allowed live GitHub repository.
  • Read current issues, issue comments, pull requests, pull request files, reviews, commits, branches, labels, milestones, README, or repository contents.
  • Check live state when the source ETL mirror may be stale or empty.

Do not use this skill for GitHub discussions or NVIDIA forums. Use source-etl-query for those mirrored sources.

Access model

  • The repository allowlist is $GITHUB_READONLY_REPOS. The legacy $GITHUB_READONLY_REPO setting remains the fallback.
  • Pass --repo owner/repository before the command when more than one repository is allowed. The helper requires an explicit selection in that case and rejects repositories outside the allowlist.
  • Requests use the OpenShell GitHub provider placeholder from GITHUB_TOKEN. Treat it as a secret placeholder: do not print it, modify it, or copy it into responses.
  • Do not run env, printenv, echo, or similar commands against GITHUB_TOKEN. The helper loads the placeholder itself.
  • Do not inspect .env files, shell environments, proxy settings, or token variables to troubleshoot GitHub. If the helper cannot authenticate or reach GitHub, it will report the error itself.
  • Only repository-scoped GET requests to api.github.com are allowed.
  • Do not use gh, git, github.com, raw.githubusercontent.com, codeload.github.com, GraphQL, or GitHub search endpoints.
  • If a request returns an OpenShell policy 403, report the policy scope instead of trying another GitHub host, another binary, or a write-like method.
  • If explicitly asked to validate that a write is blocked, do not inspect the token variable. Use direct shell expansion in the Authorization header and report only the policy error.

Write-block validation pattern:

auth="${GITHUB_TOKEN:-}"
repo="NVIDIA/OpenShell"
curl -sS -o /tmp/github-write-denied.json -w 'HTTP Status: %{http_code}\n' \
  -X POST \
  -H "Authorization: Bearer ${auth}" \
  -H 'Accept: application/vnd.github+json' \
  -H 'X-GitHub-Api-Version: 2022-11-28' \
  "https://api.github.com/repos/${repo}/issues/<number>/comments" \
  -d '{"body":"policy-validation-test"}'
cat /tmp/github-write-denied.json

Set repo to the allowed repository that the user selected.

Procedure

Always run the bundled helper script via the terminal tool. It constructs only repository-scoped GitHub REST GET requests. Prefer the generic get command and map the user's question to a repository-relative REST route plus query parameters. Select the target with --repo when the allowlist contains more than one repository. Do not invoke github-readonly-live as a shell command; it is the skill name, not an executable. Do not call a tool named github-readonly-live; use skill_view only if you need to read this instruction file. Do not search for GitHub binaries with which, command -v, ls /usr/bin, or similar commands. The canonical helper path below is the only supported live GitHub access path.

On transient helper failures such as DNS resolution errors, connection resets, or timeouts, retry the exact same helper command once. If the retry fails, give the user the helper error and stop. Do not diagnose by inspecting token env vars, .env files, proxy env vars, DNS tools, curl, gh, git, custom Python requests, or alternate GitHub hosts.

Replace NVIDIA/OpenShell in the repository-scoped examples below with the allowed repository that matches the user's request.

/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py rate-limit
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get . --fields full_name,description,open_issues_count
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get issues --param state=open --limit 20 --exclude-pulls --fields number,title,state,html_url
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get issues/<number>/comments --paginate --fields user.login,created_at,body
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get pulls --param state=open --paginate --count
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get pulls/<number>/files --paginate --fields filename,status,changes
/usr/bin/python3 /sandbox/.hermes-data/skills/github-readonly-live/scripts/github_readonly.py --repo NVIDIA/OpenShell get contents/<path>

Generic route rules:

  • Use repository-relative REST routes only: ., issues, issues/<number>, issues/<number>/comments, pulls, pulls/<number>, pulls/<number>/files, commits, branches, contents/<path>, etc.
  • Put query strings in --param KEY=VALUE, not in the route.
  • Use --paginate --count for exact counts. Use --limit only when the user asks for a sample or "latest N" items.
  • Use --fields to keep output small instead of piping to python -c, jq, or custom scripts.
  • Use --exclude-pulls on the issues route when the user asks for issues rather than PRs, because GitHub's issues endpoint includes pull requests.

Compatibility aliases such as issues, issue-counts, pulls, pull-counts, and contents are available, but the generic get command is the default pattern for new GitHub questions.

Pitfalls

  • For "how many issues" questions, use generic count: get issues --param state=all --paginate --count --exclude-pulls. Do not use GitHub search endpoints; they are outside policy by design.
  • For "how many PRs" or "how many pull requests" questions, use generic count: get pulls --param state=open --paginate --count or the requested state. Do not estimate from a single page.
  • The live GitHub scope and the source ETL mirror scope can use different repositories. Do not merge their results without naming which source each fact came from.
  • If the helper is rate-limited, report that GitHub auth was absent or exhausted; use source-etl-query only when the user's task can tolerate mirrored data.
  • The helper filters pull requests out of the issues command. Use pulls or pull-counts when the user specifically asks for PRs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.