Content
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a solid project overview and structural map of the Rocky-LTI codebase, which is genuinely useful for orientation. However, it leans toward descriptive documentation rather than actionable coding guidance — most 'Common Tasks' sections list steps without executable code examples. The content could be tightened by removing generic best practices Claude already knows and adding concrete code snippets for the project-specific patterns.
Suggestions
Add executable code examples for common tasks — e.g., a complete sample FastAPI route with Pydantic models, dependency injection, and service delegation following the project's conventions.
Add validation/verification steps to workflows — e.g., after generating an Alembic migration, include 'Review the generated migration file to verify it matches intent' and 'uv run pytest to verify no regressions'.
Remove generic advice Claude already knows (e.g., 'Type-annotate all function signatures', 'Prefer async/await for all I/O') and replace with project-specific patterns or anti-patterns unique to this codebase.
Consider splitting detailed reference content (Pydantic v2 patterns, LTI auth flow, MCP component structure) into separate files and linking from the main SKILL.md to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-organized but includes some content Claude already knows (e.g., explaining what LTI 1.3 is, what Pydantic v2 differences are, general advice like 'prefer async/await for all I/O'). The monorepo structure listing is valuable but some sections like 'Code Quality Guidelines' contain generic best practices that don't earn their tokens. | 2 / 3 |
Actionability | The 'Common Tasks' section provides step-by-step guidance but lacks executable code examples — steps like 'Add route in appropriate router.py' are directional rather than concrete. The uv commands and alembic commands are specific and actionable, but most guidance is at the 'what to do' level rather than 'how to do it with code'. | 2 / 3 |
Workflow Clarity | Multi-step workflows (adding endpoints, MCP resources, DB models) are listed with clear sequences, but lack validation checkpoints. For example, the database migration workflow doesn't include a verification step after applying migrations, and the API endpoint workflow doesn't mention testing or validation before considering the task complete. | 2 / 3 |
Progressive Disclosure | The content is organized into logical sections with headers, but everything is in a single monolithic file with no references to supporting documents. Given the breadth of topics covered (backend, frontend, infrastructure, auth, MCP, testing), some content like Pydantic v2 patterns, LTI auth flow details, or MCP component guides could be split into separate referenced files. | 2 / 3 |
Total | 8 / 12 Passed |