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., fetch README, search API docs, list available documentation pages).
Suggestions
Expand the opening line with more specific concrete actions, e.g., 'Fetches README files, searches API documentation, retrieves code examples, and browses documentation pages 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-written, actionable skill that provides concrete CLI commands and clear examples for accessing GitHub documentation via gitmcp.io. Its main weakness is the workflow section, which lists steps but lacks error handling, validation, or feedback loops for when things go wrong. The content is appropriately concise and respects Claude's intelligence.
Suggestions
Add error handling guidance to the workflow section (e.g., what to do if fetch-docs returns empty, if the repo doesn't exist, or if search yields no results)
Consider adding a brief example of a complete end-to-end interaction showing output snippets so Claude knows what to expect from each command
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It doesn't explain what GitHub is, what MCP is, or how documentation works. Every section provides concrete, necessary information without padding. | 3 / 3 |
Actionability | Every operation has a concrete, copy-paste-ready CLI command with clear argument patterns. The URL conversion examples are specific and immediately usable. Tool naming conventions are illustrated with concrete examples. | 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 a fetch fails, if a repo doesn't exist, or if search returns no results — no error handling or feedback loops are mentioned. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and headers, but everything is inline in a single file. The tool reference section 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's own help/docs is a minor gap. | 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
633b7e0
- 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.