Content
65%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.
The body is a well-structured, highly actionable runbook for the Membrane CLI workflow with concrete commands at every step, though it dangles a 'Step 2' reference and never shows how action keys map to actionIds. Its main structural weakness is that everything — including a large action catalog — is inlined in one ~180-line file with no bundle references, and destructive operations lack validation guidance.
Suggestions
Fix the dangling 'skip to Step 2' reference by numbering the workflow steps explicitly (1. connect, 2. search actions, 3. run), and add concrete recovery guidance for CONFIGURATION_ERROR/SETUP_FAILED.
Add validation guidance for destructive operations: e.g. get-time-entry / list-jobs to confirm the right record before delete-time-entry or delete-job, and verify the output after update actions.
Move the 20-row popular-actions catalog and the clientAction state reference into a references/ file (e.g. references/actions.md), keeping SKILL.md a lean overview with well-signaled one-level-deep links.
Show one concrete end-to-end example resolving an action key from the table into a real 'membrane action run' command so the <actionId> placeholder is unambiguous.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by lean, copy-pasteable commands and tables with little padding; examples: 'npm install -g @membranehq/cli@latest', 'membrane connection ensure "https://www.clicktime.com/" --json'. Minor over-explanation could be trimmed — the ClickTime marketing-style opener ('It's used by businesses to track employee time...'), 'This is the fastest way to get a connection', and 'so you can focus on the integration logic rather than auth plumbing' — keeping it at the 'efficient; minor instances of over-explanation' anchor rather than 5. | 4 / 5 |
Actionability | Nearly every section gives an executable command (login, connection ensure/get with --wait, action list with --intent, action run with --input JSON, request with a flags table), matching 'mostly executable guidance; concrete code or commands with minor gaps'. The gaps: 'If the returned connection has state: READY, skip to Step 2' references a step label that doesn't exist, and the popular-actions table gives action keys (e.g. 'create-time-entry') without ever showing how to resolve a key into the <actionId> used by 'membrane action run'. | 4 / 5 |
Workflow Clarity | A real sequence exists (install → login → connection ensure → poll/handle state → search actions → run/proxy) with a genuine feedback loop for connection states (BUILDING → poll, CLIENT_ACTION_REQUIRED → act and re-poll), but checkpoints are implicit in section order rather than numbered steps, the 'Step 2' pointer dangles, and CONFIGURATION_ERROR recovery is just 'check the error field'. More importantly, the skill surfaces destructive operations (delete-time-entry, delete-job, delete-user-adjacent actions in the popular table) with no validation/verification guidance, which caps workflow clarity at 3. | 3 / 5 |
Progressive Disclosure | The single file has good section structure (Overview, Install, Authentication, Connecting, Searching, Running, Proxy, Best practices) but there is no bundle at all — no references/, scripts/, or assets/ — and ~180 lines of content that belongs in separate files is inlined, notably the 20-row popular-actions catalog and the clientAction state documentation. This fits 'some structure but could be better organized; content that should be separate is inline' rather than the 2 anchor, since structure is not minimal and navigation is easy. | 3 / 5 |
Total | 14 / 20 Passed |