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, token-efficient CLI reference whose commands and pitfalls are concrete and executable. Its main defect is broken progressive disclosure: two referenced files (references/configuration.md, references/cli-reference.md) are absent from the bundle, and the naming-alias blockquote duplicates detail that belongs in the API references.
Suggestions
Ship references/configuration.md and references/cli-reference.md in the skill bundle (or remove the pointers), so the closing line "See references/configuration.md for the full [chunking] schema and references/cli-reference.md for every chunk flag" resolves instead of dead-ending.
Move the 8-line naming-alias blockquote (Python dataclass kwargs, Rust struct fields, TOML/JSON serde aliases, Node interface) into references/python-api.md / references/rust-api.md and keep only the one-line practical takeaway inline.
Add a light verification step after chunking, e.g., "check chunk_count / jq '.chunks | length' matches the expected size" — it costs one line and closes the workflow's only feedback-loop gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and example-driven (e.g., "xberg extract report.pdf --chunk --format json | jq '.chunks | length'", the chunker-type table, the "Picking parameters" ranges) with almost no explanation of concepts Claude already knows. The 8-line naming-alias blockquote ("the public Python ChunkingConfig (a dataclass) uses constructor kwargs max_characters / overlap; the Rust core struct fields are also...") is over-explanation that could be trimmed or deferred to the API references. | 4 / 5 |
Actionability | Every section gives copy-paste-ready commands with real flags ("xberg chunk --text \"$(cat README.md)\" --chunker-type markdown", "--chunking-tokenizer Xenova/gpt-4o --chunk-size 512") and the Python example is complete and executable. Concrete numbers in "Picking parameters" ("500–1000 chars (or 256–512 tokens) with 10–20% overlap") cover the common cases. | 5 / 5 |
Workflow Clarity | Usage paths are clearly organized (inline extraction vs standalone chunk, chunker types, tokenizer sizing, config file) and the "Common pitfalls" section documents error conditions ("Overlap ≥ size — rejected on extract; clamped to size / 4", "Tokenizer without the feature ... errors", "the standalone chunk command bails on empty text"). Chunking is non-destructive so the validation cap does not apply, but there are no explicit verification steps after chunking (e.g., checking chunk_count or chunk contents), which keeps it below a 5. | 4 / 5 |
Progressive Disclosure | Sections are well-organized and the references are clearly signaled, but the body points to files that do not exist in the bundle: "See references/configuration.md for the full [chunking] schema and references/cli-reference.md for every chunk flag" — there is no references/ directory. The pointer to "references/python-api.md and references/rust-api.md in the sibling xberg skill" also cannot be verified. Broken navigation defeats the disclosure chain, matching the anchor for structure present but poorly realized. | 3 / 5 |
Total | 16 / 20 Passed |