Content
82%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 strong, dense deployment skill: every command is runnable as written, endpoint/request/env-var documentation is exact and source-anchored, and the workflow is clearly sequenced with a health-check checkpoint and thoughtful operational gotchas (no-PHI logging, keep_mapping sensitivity, cold-start tuning). Its weaknesses are minor — duplicated auth guidance across sections, recovery guidance detached from the workflow steps, and reference-grade schema detail inlined in the main file.
Suggestions
State the no-built-in-auth/CORS/TLS guidance once (keep the Edge cases entry, which is the more detailed of the two) and have Workflow step 3 cross-reference it, removing the duplicated reverse-proxy advice and the repeated launch command.
Add an explicit feedback loop to the workflow: after the health-check step, note what to do when /health fails or a request returns 504/422 (e.g., check profile timeout, reduce input size, fix the rejected field per the error envelope), pulling that recovery guidance out of Edge cases and into the sequence.
Move the full request-field enumerations for AnalyzeRequest/PIIExtractRequest/PIIDeidentifyRequest (with defaults and enum values) into a references/ file (e.g. API.md), keeping a compact endpoints table in SKILL.md, and include one concrete success-response example alongside the error envelope.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes competence — no explanation of what FastAPI/REST/uvicorn are, and everything is carried by tables and runnable commands. Minor trimmable duplication keeps it below anchor 5: the auth/TLS advice appears in both Workflow step 3 ("Place a reverse proxy or gateway (API keys/mTLS, CORS allow-list) ahead of the app — it has none built in") and again nearly verbatim in Edge cases ("No built-in auth/CORS/TLS... Put it behind your own reverse proxy / API gateway"), and the launch command appears four times across Quick start, env-var example, Workflow, and Dockerfile. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: `pip install "openmed[service]"`, `python -m openmed.service.logging --host 127.0.0.1 --port 8000`, an in-process `create_app()` snippet, working curl examples for /health, /analyze, and /pii/deidentify, a complete env-var table with defaults, exact enum values and defaults for every request field, a stable error envelope with status codes, and a full Dockerfile. The common deployment cases are all covered concretely; the only elided detail is the success-response shape, which is minor. | 5 / 5 |
Workflow Clarity | The six-step workflow is clearly sequenced (install+launch → configure env → front with auth/TLS → health-check+warm → call endpoints → manage memory) and includes a validation checkpoint ("Poll GET /health; preloaded models warm during the lifespan startup"). It falls short of anchor 5 because the recovery guidance (504 → larger profile/pre-chunking, 422 → field-level reasons) lives in Edge cases rather than being an explicit feedback loop inside the workflow steps, so checkpoints are present but error-recovery is not integrated. | 4 / 5 |
Progressive Disclosure | The body is a single well-organized file with clean, scannable sections (When to use, Quick start, Endpoints, Config, Workflow, Containerizing, Hand-off, Edge cases, Standards) and only one-level-deep pointers (source files like `openmed/service/app.py` and external URLs — no nested reference chains, and no bundle files exist to bury anything). It sits between anchors 4 and 5: at ~170 lines it exceeds the 'simple skill' threshold, and reference-grade material (the full request-field enumerations for three schemas) is inlined where a references/ file could keep SKILL.md leaner, which is a minor organization gap rather than a structural problem. | 4 / 5 |
Total | 17 / 20 Passed |