aps-doc-hist-union

Expert documentation generation for hist-union workflows. Documents historical and incremental table combination strategies, schema validation, time-based partitioning, and backfill processes. Use when documenting hist-union layers.

Quality

55%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./aps-doc-skills/hist-union/SKILL.md

Quality

Content

42%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill conveys a clear purpose and a usable template, but is padded with redundant emphatic instructions and inlines a large template that belongs in a reference file. Workflow checkpoints for verifying extracted data are implicit rather than explicit.

Suggestions

Move the ~120-line documentation template into references/ (e.g. TEMPLATE.md) and reference it from SKILL.md to cut tokens and improve progressive disclosure.

Tighten the emphatic headers and remove repeated 'NO placeholders / ONLY real data' lines; state the constraint once.

Add an explicit validation checkpoint (e.g. 'Verify each extracted table name/SQL against the source file before writing it into the doc') to lift workflow clarity above the batch-operation cap of 3.

Dimension	Reasoning	Score
Conciseness	The body is noticeably padded: large ALL-CAPS/emoji headers, repeated 'NO placeholders / ONLY real data' injunctions, and a full ~120-line template whose braces could be trimmed, re-explaining what Claude already knows.	2 / 5
Actionability	It gives a concrete template and lists files to read (.dig, .sql, .yml, inc_log), but the template is a placeholder skeleton ({Real SQL from codebase}) rather than executable, copy-paste-ready guidance.	3 / 5
Workflow Clarity	A rough sequence is present (ask for path -> Glob verify -> STOP if unreadable -> fill template), but for a batch documentation task it lacks an explicit validate/verify checkpoint confirming extracted data is real before publishing.	3 / 5
Progressive Disclosure	Sections are organized, but the full documentation template is inlined in SKILL.md instead of living in a references file, and there are no bundle files to offload the bulky template and usage notes.	3 / 5
	Total	11 / 20 Passed

Description

67%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description clearly states both capability and trigger for a well-scoped niche, with multiple concrete actions. Its main weakness is trigger-term naturalness — the phrasing leans technical and lacks the variations a user would spontaneously say.

Suggestions

Add natural user-facing trigger phrases and file extensions, e.g. 'Use when documenting hist-union workflows, .dig files, or UNION ALL incremental-load patterns'.

Include a synonym or two users might say ('historical+incremental table merge', 'watermark backfill docs') to broaden trigger matching.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('Documents historical and incremental table combination strategies, schema validation, time-based partitioning, and backfill processes') with only minor coverage gaps.	4 / 5
Completeness	Both 'what' (documentation generation for the listed strategies) and 'when' ('Use when documenting hist-union layers') are present, though the trigger is somewhat narrow.	4 / 5
Trigger Term Quality	Contains relevant domain terms (hist-union, backfill, partitioning, schema validation) but few natural user phrases and no file extensions or synonyms a user would actually say.	3 / 5
Distinctiveness Conflict Risk	The 'hist-union' niche is specific and unlikely to collide with unrelated skills, with only minor overlap risk against a general documentation skill.	4 / 5
	Total	15 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: treasure-data/td-skills
Path: aps-doc-skills/hist-union/SKILL.md
Commit: 1a0845f

Reviewed: 3 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.