docs-contribution-router
Route documentation contributions to the right content type, placement, template, and escalation path — before the contributor writes a single line.
60
71%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/documentation/docs-contribution-router/SKILL.mdQuality
Discovery
50%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description communicates a clear purpose — triaging documentation contributions before writing begins — but lacks explicit trigger guidance ('Use when...') and concrete action verbs. The language is process-oriented rather than user-oriented, making it harder for Claude to match against natural user requests.
Suggestions
Add an explicit 'Use when...' clause with natural trigger phrases, e.g., 'Use when a contributor asks where to put new documentation, which template to use, or how to structure a doc contribution.'
Replace abstract routing language with concrete actions, e.g., 'Identifies the correct content type (tutorial, reference, guide), suggests file placement, selects the appropriate template, and flags items needing review escalation.'
Include natural user-facing keywords like 'new doc', 'where does this go', 'doc template', 'contribution guide' to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain (documentation contributions) and describes a general action (routing to content type, placement, template, escalation path), but these are somewhat abstract categories rather than concrete, specific actions like 'create a template' or 'assign a reviewer'. | 2 / 3 |
Completeness | The 'what' is partially addressed (routing documentation contributions to the right type/placement/template/escalation), but there is no explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric guidelines. | 2 / 3 |
Trigger Term Quality | Terms like 'documentation', 'contributions', 'content type', 'template', and 'escalation path' are somewhat relevant but not strongly aligned with what a user would naturally say. Users might say 'where should I put this doc' or 'how to contribute docs' rather than these more process-oriented terms. | 2 / 3 |
Distinctiveness Conflict Risk | The description is somewhat specific to documentation contribution routing, which is a fairly niche domain, but 'documentation' is broad enough that it could overlap with skills about writing documentation, editing docs, or managing doc repositories. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
92%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 routing skill that efficiently maps contributor intent to concrete action plans with specific file paths, naming conventions, and escalation rules. The workflow is clear with explicit validation checkpoints (HARD STOP warnings, diff review, CODEOWNER gates). The main weakness is that the skill heavily depends on reference files that are not provided in the bundle, making it impossible to verify completeness of the referenced workflows.
Suggestions
Provide the referenced bundle files (e.g., `references/api-reference-flow.md`, `references/placement-decisions.md`) so the skill is self-contained and references can be verified.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and well-structured. Every section serves a clear purpose — routing tables, key facts as bullet lists, and output templates. There's no explanation of concepts Claude already knows (e.g., what markdown is, what frontmatter does). The tables are efficient and scannable. | 3 / 3 |
Actionability | The skill provides concrete file paths, naming conventions (e.g., `_setup-<slug>.mdx`, `_section-after-setup-<slug>-common-workflows.mdx`), exact frontmatter templates, escalation severity mappings, and a structured output format. The contributor gets a specific, copy-paste-ready action plan from every routing decision. | 3 / 3 |
Workflow Clarity | The intent classifier table provides a clear entry point, each branch has sequenced steps with explicit validation checkpoints (e.g., 'HARD STOP' for generated files, 'Review the git diff before committing', escalation severity gates with required approvals). The agent connector section includes a feedback loop: edit templates → run sync → review diff → question unexpected changes. | 3 / 3 |
Progressive Disclosure | The skill references multiple external files (e.g., `references/api-reference-flow.md`, `references/agent-connector-flow.md`, `references/placement-decisions.md`, `references/screenshot-workflow.md`, JSON config files) with clear one-level-deep navigation. However, no bundle files were provided, so we cannot verify these references actually exist. The inline content is appropriately scoped as an overview, but the heavy reliance on absent reference files is a concern — the skill would be incomplete without them. | 2 / 3 |
Total | 11 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 10 / 11 Passed | |
- Repository
- saif-shines/devex-kit
- Commit
b683754
- 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.