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
65
77%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/read-github/SKILL.mdQuality
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, retrieve specific pages).
Suggestions
Expand the opening line with more specific concrete actions, e.g., 'Fetches README files, searches API documentation, retrieves specific doc 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
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, actionable skill with clear CLI examples and good structure. Its main weaknesses are minor redundancy between the CLI usage and MCP tools sections, and the lack of error handling or validation guidance in the workflow. The referenced script (scripts/gitmcp.py) is not provided in the bundle, which creates a gap in progressive disclosure.
Suggestions
Remove or consolidate the 'Available MCP Tools' section with the CLI Usage section to reduce redundancy
Add basic error handling guidance to the workflow (e.g., what to do if fetch-docs returns empty or the repo URL is invalid)
Include the referenced scripts/gitmcp.py in the bundle or note its expected location clearly
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient but includes some redundancy — the 'Available MCP Tools' section largely repeats what's already shown in the CLI Usage section, and the tool naming convention explanation could be tighter. The workflow section at the end is somewhat obvious given the preceding content. | 2 / 3 |
Actionability | Every operation has a concrete, copy-paste-ready CLI command with clear argument patterns. The URL conversion examples are specific and the tool naming convention is illustrated with multiple 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 fetch-docs returns empty, if the repo doesn't exist, or if search returns no results. For a read-only operation this is less critical, but error handling guidance is absent. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and sections, but it's all inline in a single file. The bundle has no supporting files, yet the skill references 'scripts/gitmcp.py' without providing it. For a skill of this length (~80 lines), the organization is adequate but the missing script reference is a gap. | 2 / 3 |
Total | 9 / 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
d3983b1
- 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.