Content
85%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A lean, well-organized docs-lookup skill body with an explicit return format and a clear topic-to-file map. Its critical defect is that every referenced reference file is missing from the bundle, so the skill cannot actually function as written.
Suggestions
Add the four referenced files (swiftdata-index.md, swiftdata-model.md, swiftdata-modelcontext.md, swiftdata-query.md) to the bundle — currently none of them exist, so the skill's entire content is unreachable.
Specify how to search the files (e.g., grep by symbol name, or read swiftdata-index.md first), so the Explore agent has a concrete search procedure.
Clarify fallback behavior when a question spans multiple files or no file matches (e.g., start from swiftdata-index.md).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 27-line body is lean and assumes Claude's competence: no concept explanations, no padding, and every line directs behavior ('Search these docs to answer questions about SwiftData APIs', 'Always include: 1. Summary... 2. File paths'). Matches the 'lean and efficient; every token earns its place' anchor. | 5 / 5 |
Actionability | Provides a concrete topic-to-file mapping ('swiftdata-model.md - @Model macro and model definition', 'swiftdata-query.md - @Query property wrapper for fetching data') and an explicit return format. Minor gap: it never says how to search the files (e.g., grep/read), so it fits 'mostly executable guidance with minor gaps' rather than 5. | 4 / 5 |
Workflow Clarity | A simple single-purpose skill with an unambiguous action — search the docs, answer the question — and a mandated output structure (Summary, then File paths). Per the simple-skill exception, a clear single action with explicit output format scores 5; there are no risky or batch operations requiring validation. | 5 / 5 |
Progressive Disclosure | The structure is well designed for disclosure (overview plus a 'Files' section with one-level-deep, clearly labeled references), but the referenced files do not exist: no references/, scripts/, or assets/ directories are present and none of the four listed files (swiftdata-index.md, swiftdata-model.md, swiftdata-modelcontext.md, swiftdata-query.md) are anywhere in the bundle. The disclosure chain is broken as shipped, so it cannot score 4-5 despite good on-paper organization. | 3 / 5 |
Total | 17 / 20 Passed |