Content
93%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.
An exemplary instruction-style skill body: lean, action-oriented, with a clearly sequenced multi-phase workflow and disciplined progressive disclosure backed by a complete, real bundle. The single gap is the missing explicit linter-failure recovery loop, which keeps workflow_clarity at 4.
Suggestions
Add one line after the linter command specifying the error-recovery loop, e.g. 'If okf_linter reports errors, fix the flagged concepts and re-run until it passes before regenerating the index.'
State what a linter failure looks like or the most common failure modes (missing type, broken link) so recovery is actionable without reading the script.
Clarify the fallback path when disk access is unavailable mid-phase (principle 10 covers writing files without disk, but the per-phase loop in step (d) does not mention it).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~80-line body is dense and directive with no filler: conformance rules are compressed to 5 numbered lines with detail delegated to references, principles are one line each, and commands are shown once. The only explanation of an unknown concept (OKF) is necessary, since it is a custom format Claude would not know. Not level 4 because no section is padded or restated beyond the deliberate one-line summary-plus-reference pattern. | 5 / 5 |
Actionability | Fully executable guidance: copy-paste bash invocations for all three scripts with realistic flags ('python scripts/scaffold_bundle.py "My Company" --out ./my-company --has-product --has-tech'), a concrete link syntax example ('[Identity](../00-fundacao/identidade.md)'), a recommended flow, and a numbered 'How to start' procedure. Not level 4 because the common cases (scaffold, per-phase loop, validation, index regeneration) are each covered by specific, runnable commands or explicit steps. | 5 / 5 |
Workflow Clarity | The sequence is clear with most checkpoints present: interview-before-build gating, 'Stop and wait' for answers, 'Confirm before generating... ask for ok', and an explicit okf_linter validation step after each phase. Not level 5 because the error-recovery loop is incomplete — the body says to run okf_linter but never states what to do on linter failure (fix and re-run), leaving that feedback loop implicit. Not level 3 because validation checkpoints are explicit and repeated per phase, not merely implicit. | 4 / 5 |
Progressive Disclosure | SKILL.md is a clean overview with well-signaled, one-level-deep references: 3 reference files, 4 assets, and 3 scripts, all verified to exist, each linked inline with a one-line description of its purpose and enumerated again in a References/Assets section. Reference files link only to siblings, so no nested read chains. Not level 4 because there is no content that should have been split out still inlined, and every navigation path is explicit. | 5 / 5 |
Total | 19 / 20 Passed |