Content
75%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 well-structured, highly actionable skill body with real executable commands, a working bundle script, and clearly signaled references. The main weaknesses are inline duplication of the schema reference content, a non-executable pseudo-API in the integration examples, and a meta-commentary section that adds tokens without guidance value.
Suggestions
Replace the inline Core Types and Constraints listings with a brief summary plus a pointer to references/schema.md, since that file already contains the full definitions — this would remove ~60 duplicated lines.
Rewrite the Integration Patterns Python snippets against the actual interface (e.g., subprocess calls to scripts/ontology.py) or explicitly label them as illustrative pseudocode.
Delete or drastically shorten the "Instruction Scope" section; its scope/limitations content is reviewer-facing meta-commentary rather than runtime guidance, and the validation caveats could fold into the Constraints section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with tables and executable commands rather than prose, but the full Core Types and Constraints listings duplicate references/schema.md, and the closing "Instruction Scope" section ("this is within scope", "documentation-only unless implemented in code") is meta-commentary that could be trimmed. Not 5 because of this removable redundancy; not 3 since the padding is minor relative to the whole. | 4 / 5 |
Actionability | Workflows and Quick Start give copy-paste-ready CLI commands ("python3 scripts/ontology.py create --type Person --props '{...}'") and the bundle script exists, but the Integration Patterns snippets use a pseudo-API ("ontology.create(\"Commitment\", {...})") that is not executable as written — minor gaps, so not 5. | 4 / 5 |
Workflow Clarity | Quick Start sequences init → schema → create, and the planning section has an explicit checkpoint ("Each step is validated before execution. Rollback on constraint violation") plus a dedicated validate command. Not 5 because validation is described but not wired into the Quick Start sequence as an explicit step, and there is no fix-and-retry loop shown. | 4 / 5 |
Progressive Disclosure | References section clearly signals the two real one-level-deep files ("references/schema.md — Full type definitions and constraint patterns", "references/queries.md — Query language and traversal examples") and the script bundle exists as listed. Not 5 because the ~30-line inline Core Types and Constraints sections duplicate content that already lives in references/schema.md, a minor organization gap. | 4 / 5 |
Total | 16 / 20 Passed |