review-public-api
Use this skill when the user asks to review a DuckDuckGo Android public API proposal. If given an Asana task URL, first fetch the task and confirm it is an API proposal before invoking — do not invoke just because a URL was paired with "review". Confirmed signals: the task title contains "API Proposal"; the task belongs to project 1212149061863360 (API Proposals); or the description proposes changes to a -api module. Also invoke for any request to review, evaluate, or give feedback on a proposal pasted inline or provided as a file. Covers phrases like "review my API proposal", "is this API design good?", "check my public interface", "I'm about to submit an API proposal". When the user shares Kotlin code, only invoke if the code is explicitly from or intended for a -api module — do not invoke for impl-only changes or general Kotlin questions. IMPORTANT: Always apply these instructions directly — never delegate or summarise.
90
88%
Does it follow best practices?
Impact
94%
1.08xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Quality
Discovery
100%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 an excellent skill description that thoroughly covers what the skill does, when to invoke it, and critically, when NOT to invoke it. The inclusion of specific Asana project IDs, explicit trigger phrases, and clear boundary conditions (e.g., not for impl-only Kotlin changes) makes it highly actionable for skill selection. The only minor issue is the use of second-person voice in places and the instruction 'Always apply these instructions directly — never delegate or summarise' which is more of a runtime instruction than a selection-relevant description.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists multiple concrete actions: reviewing DuckDuckGo Android public API proposals, fetching Asana tasks, confirming task type via specific signals (project ID, title, module), evaluating inline or file-based proposals, and checking Kotlin code for -api modules. | 3 / 3 |
Completeness | Clearly answers both 'what' (review DuckDuckGo Android public API proposals, evaluate API designs, check public interfaces) and 'when' with extensive explicit trigger guidance including positive triggers, negative triggers (do not invoke for impl-only changes), and specific confirmation signals. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger phrases: 'review my API proposal', 'is this API design good?', 'check my public interface', 'I'm about to submit an API proposal', plus mentions of Asana task URLs, Kotlin code, and -api modules. These are terms users would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a very specific niche: DuckDuckGo Android API proposals, a specific Asana project ID, -api module scope, and explicit exclusion criteria (not for general Kotlin questions, not for impl-only changes, not just because a URL is paired with 'review'). Very unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with a clear multi-step workflow, explicit validation gates, and concrete examples throughout. Its main weakness is length — the 16 heuristics with inline examples make it a substantial document that could benefit from progressive disclosure via a separate heuristics reference file. The content is well-written and avoids most unnecessary explanation, though a few heuristic descriptions could be tightened.
Suggestions
Consider extracting the 16 heuristics (H1–H16) into a separate HEURISTICS.md file, with SKILL.md containing a summary checklist that links to the detailed descriptions — this would significantly reduce token cost for routine invocations.
Trim heuristic explanations that restate well-known design principles (e.g., H1's single responsibility explanation) to just the project-specific guidance and examples.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is well-structured and mostly efficient, but some heuristics include explanations Claude could infer (e.g., H1's 'if you can describe it with and, it probably needs splitting' is a well-known principle). The table in Step 4 and the heuristic descriptions are reasonably tight but could be trimmed in places. Overall it's dense but not padded. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific Asana API opt_fields, exact search strategies for resolving module locations, a copy-paste-ready diagram template, specific good/bad code examples for each heuristic, and a clear three-tier output structure. The instructions are precise enough to follow without ambiguity. | 3 / 3 |
Workflow Clarity | The seven-step workflow is clearly sequenced with explicit validation checkpoints — Step 2 has a hard stop ('Do not proceed... with unresolved module locations'), Step 3 must complete before heuristics, and the final synthesis has a clear verdict gate. The feedback loop for unresolved types (ask the user) is well-defined. | 3 / 3 |
Progressive Disclosure | The content is a single monolithic file with no references to supporting files, which is understandable given no bundle exists. However, at ~200+ lines with 16 detailed heuristics, the heuristic definitions could benefit from being split into a separate reference file with the SKILL.md providing a summary checklist and linking out for details. | 2 / 3 |
Total | 10 / 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 |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- duckduckgo/Android
- Commit
adccd8d
- 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.