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

Quality

77%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/read-github/SKILL.md

Quality

Content

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

Description

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

Validation

100%

Warnings & errors only

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: about 2 months ago

Table of Contents

Discovery Implementation Validation

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.