read-github
Read and search GitHub repository documentation via gitmcp.io MCP service. **WHEN TO USE:** - User provides a GitHub URL - User mentions a specific repo in owner/repo format - User asks "what does this repo do?", "read the docs for X repo", or similar - User wants to search code or docs within a repo
87
84%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-structured skill description with a clear 'WHEN TO USE' section that provides explicit trigger scenarios. The trigger terms are natural and cover common user phrasings. The main weakness is that the capability description could be more specific about what concrete actions are performed beyond 'read and search' (e.g., retrieve README, search API docs, list available documentation pages).
Suggestions
Expand the opening line with more specific concrete actions, e.g., 'Retrieve README files, search API documentation, browse repository wikis, and explore code documentation from GitHub repositories via gitmcp.io MCP service.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (GitHub repository documentation) and some actions (read, search), but doesn't list multiple concrete actions comprehensively. 'Read and search' is somewhat specific but could be more detailed about what exactly is extracted or returned. | 2 / 3 |
Completeness | Clearly answers both 'what' (read and search GitHub repository documentation via gitmcp.io MCP service) and 'when' with an explicit 'WHEN TO USE' section listing four specific trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would actually say: 'GitHub URL', 'owner/repo format', 'what does this repo do?', 'read the docs for X repo', 'search code or docs within a repo'. These cover multiple natural phrasings and variations. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to GitHub repository documentation via a specific MCP service (gitmcp.io), with distinct triggers like GitHub URLs and owner/repo format. Unlikely to conflict with general documentation or code skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted, concise skill that provides clear, actionable CLI commands for accessing GitHub documentation via gitmcp.io. Its main strengths are token efficiency and concrete executable examples. The primary weakness is the workflow section, which lists steps but lacks error handling guidance or validation checkpoints for when operations fail or return unexpected results.
Suggestions
Add error handling guidance to the workflow section (e.g., what to do if fetch-docs returns empty or the repo URL is invalid)
Include a brief validation step in the workflow, such as checking that documentation was successfully retrieved before proceeding to search operations
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. Every section serves a clear purpose—URL conversion, CLI commands, tool naming conventions, and workflow. No unnecessary explanations of what GitHub is or how MCP works. | 3 / 3 |
Actionability | Provides fully executable CLI commands with clear argument patterns for every operation. The URL conversion examples are concrete, tool naming convention is illustrated with multiple examples, and all commands are copy-paste ready. | 3 / 3 |
Workflow Clarity | The workflow section at the end provides a reasonable sequence but lacks validation checkpoints. There's no guidance on what to do if fetch-docs returns empty, if the repo doesn't exist, or if search returns no results—no error handling or feedback loops. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear sections, but everything is inline in a single file. The MCP tools reference and CLI usage details could potentially be split out, though for this length (~80 lines) it's borderline acceptable. The lack of any cross-references to additional resources or the script source slightly limits navigation. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- am-will/codex-skills
- Commit
ca2c3b3
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.