Content
78%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 highly actionable, information-dense skill: complete YAML and CLI examples for both engine modes, concrete error codes, and real operational guidance. Its weaknesses are structural rather than substantive — reference-grade material (observers defaults, metrics, RBAC schema) is inlined in a single 185-line file with no bundle files, and version-sensitive notes are not quarantined in a versions/deprecated section.
Suggestions
Split reference-grade material into one-level-deep bundle files (e.g., references/observers.md with the full defaults table and metrics list, references/rbac.md with the RBAC settings schema and observer-RBAC rules), keeping SKILL.md as a mode-selection overview with short examples and clearly signaled links.
Add an explicit change → restart → verify sequence for configuration changes (edit file, restart Compose/engine, then confirm with compose::status / engine::workers::list), including recovery steps when startup fails with UNSUPPORTED_CONFIG_WORKERS.
Move version-sensitive statements ("Since 0.25 the engine reads...", "(0.25 engine)") into a dedicated versions/compatibility note so time-sensitive facts do not age the core instructions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes competence — no space is spent explaining YAML, WebSockets, or systemd — and every section carries iii-specific facts (e.g., "engine.url defaults to ws://127.0.0.1:49134", "compose::add never edits engine: or restarts the engine"). It falls short of the lean 5 anchor because version-number references ("Since 0.25 the engine reads...", "(0.25 engine)") and a few trimmable asides ("Check the rbac-proxy worker's docs for the version that forwards the observe messages") are not isolated in a deprecation/versions section. | 4 / 5 |
Actionability | Both configuration modes have complete, copy-paste-ready YAML blocks and exact CLI invocations ("iii compose --namespace orders-daemon --up --file worker-compose.yaml", "iii trigger -n orders-daemon compose::add worker=rbac-proxy", "iii --config config.yaml"), plus concrete error codes (UNSUPPORTED_CONFIG_WORKERS, LIMIT_EXCEEDED, FORBIDDEN), named metrics, and the full observers defaults block. This fully covers the common cases with executable material, matching the top anchor. | 5 / 5 |
Workflow Clarity | The two modes are clearly separated, each with its own start command, and operational verification is provided ("Use compose::status for process ownership and engine::workers::list for live connections", "Use iii ps to find iii processes... and iii kill --orphans"). It is not a 5 because there is no explicit ordered change → restart → verify sequence, and validation around risky operations (engine restart, iii kill) is listed as tools rather than explicit checkpoints with recovery steps. | 4 / 5 |
Progressive Disclosure | Section headers (Managed Compose engine, Observers, RBAC, Directly supervised engine, Security and operations, When to Use, Boundaries) are clear and navigation is easy, but the skill is ~185 lines with no bundle files at all: the full observers defaults table, the metric name reference, and the multi-paragraph RBAC schema details are sizable reference material inlined in SKILL.md that belong in one-level-deep reference files. This matches the 'content that should be separate is inline' anchor rather than the good-but-minor-gaps anchor at 4. | 3 / 5 |
Total | 16 / 20 Passed |