using-gh-cli-search
Skill9 starsChanged 12 months agoMITView on GitHub
MANDATORY skill when users mention GitHub CLI searches - establishes non-negotiable requirement to use gh-cli-search skills for correct syntax, quoting, and platform handling
In this repository8 other files it gives its agents.
- gh-cli-setupSkill
- gh-search-codeSkill
- gh-search-commitsSkill
- gh-search-issuesSkill
- gh-search-prsSkill
- gh-search-reposSkill
- gh-searchSkill
- testing-gh-skillsSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
If a user asks ANYTHING about GitHub CLI searching, you MUST use the appropriate gh-cli-search skill.
- Very specific: line 18
When a user message mentions ANY of these, you MUST use gh-cli-search skills:
- Distinctive: line 43
If you catch yourself thinking ANY of these thoughts, STOP.
- Very specific: line 53
Why: Every time you skip these skills for "simple" gh CLI questions, you give incorrect commands.
- Distinctive: line 88
Use the Skill tool to load the appropriate gh-search-* skill
- Distinctive: line 90
Follow the skill's guidance exactly
- Distinctive: line 94
Use the gh-cli-setup skill
- Distinctive: line 95
Follow its installation/troubleshooting steps
- Distinctive: line 114
Not optional. Not negotiable.
- Distinctive: line 116
Use it every single time.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
<EXTREMELY-IMPORTANT>
If a user asks ANYTHING about GitHub CLI searching, you MUST use the appropriate gh-cli-search skill.This is not a suggestion. This is not optional. You cannot rationalize your way out of this.
Why: GitHub CLI search syntax is full of pitfalls. The -- flag. Quoting rules. PowerShell escaping. Platform differences. You WILL get it wrong without the skills. The user will copy-paste your broken command. They will waste time debugging YOUR mistake.
</EXTREMELY-IMPORTANT>
GitHub CLI Search Protocol
MANDATORY DETECTION PROTOCOL
When a user message mentions ANY of these, you MUST use gh-cli-search skills:
- ☐ Searching on GitHub
- ☐ Finding code/issues/PRs/commits/repos
- ☐
gh searchcommand - ☐ GitHub CLI queries
- ☐ Installing/troubleshooting gh CLI
If detected → Use the Skill tool to load the appropriate gh-cli-search skill
Available Skills
You have access to these gh-cli-search skills:
- gh-search-code - Searching for code across repositories
- gh-search-commits - Searching commit history
- gh-search-issues - Searching issues (and PRs)
- gh-search-prs - Searching pull requests specifically
- gh-search-repos - Searching for repositories
- gh-cli-setup - Installation and troubleshooting
Pick the right skill. Use the Skill tool. Follow it exactly.
Common Rationalizations That Mean You're About To Fail
If you catch yourself thinking ANY of these thoughts, STOP. You are about to give the user a broken command.
- "This is just a simple search query" → WRONG. Simple queries still need correct quoting and the
--flag for exclusions. - "I know gh CLI syntax" → WRONG. You know SOME of it. The skills know ALL of it, including edge cases.
- "I'll just construct the command myself" → WRONG. You will forget the
--flag. Or quote incorrectly. Or miss PowerShell escaping. - "The user didn't explicitly say 'gh search'" → WRONG. If they're asking about GitHub searching via CLI, they need these skills.
- "I can figure out the syntax quickly" → WRONG. The skills exist because this is NOT quick. You will make mistakes.
- "Let me try without the skill first" → WRONG. The skill IS the first step. Not the fallback.
- "This doesn't need the full skill treatment" → WRONG. Every GitHub CLI search command needs correct syntax. Use the skill.
Why: Every time you skip these skills for "simple" gh CLI questions, you give incorrect commands. The -- flag gets missed. Quoting breaks. PowerShell fails. The user's time is wasted.
The -- Flag Will Bite You
The most common mistake: Forgetting the -- flag before queries with exclusions.
Without the skill, you WILL write:
gh search issues "is:open -label:bug" # BROKEN - shell interprets -label as a flagThe skill ensures you write:
gh search issues -- "is:open -label:bug" # CORRECTThis is not optional. This is why the skills exist.
What Happens When You Skip The Skill
- You construct a command from memory
- You forget the
--flag for exclusions - You mis-quote something
- You miss PowerShell's
--%requirement - User copies your command
- Command fails
- User has to debug YOUR mistake
- Trust in your responses decreases
Using the skill takes 30 seconds. Debugging your broken command takes 10 minutes.
Protocol Summary
User mentions GitHub CLI searching:
- Identify which type: code/commits/issues/PRs/repos/setup
- Use the Skill tool to load the appropriate gh-search-* skill
- Announce which skill you're using
- Follow the skill's guidance exactly
- Provide the correct, tested command
User asks about installation/troubleshooting:
- Use the gh-cli-setup skill
- Follow its installation/troubleshooting steps
This Is About Correctness
These skills are not "nice to have" documentation. They are battle-tested patterns that prevent the specific, predictable mistakes you make when constructing gh CLI commands without them.
The skills encode:
- Where the
--flag is required - Exact quoting rules for each platform
- PowerShell escape sequences
- Available flags and their syntax
- Common pitfalls and how to avoid them
You cannot replicate this from memory. Stop trying.
Summary
User asks about GitHub CLI searching → You MUST use the gh-cli-search skill.
Not optional. Not negotiable. The skill exists to prevent you from giving broken commands.
Use it every single time.
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
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.

