aps-doc-golden

Expert documentation generation for golden layers. Detects SCD types, documents business rules, metric definitions, aggregation logic, and data quality scoring. Use when documenting golden layer tables.

Quality

50%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

Optimize this skill with Tessl

npx tessl skill review --optimize ./aps-doc-skills/golden/SKILL.md

Quality

Discovery

85%

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

This is a solid, well-structured skill description that clearly defines specific capabilities and includes an explicit 'Use when' trigger. Its main weakness is that the trigger terms are quite technical and narrow—users who need this skill might describe their needs using broader data warehousing terminology that isn't captured here. The description would benefit from additional natural language trigger terms to improve discoverability.

Suggestions

Expand trigger terms to include common variations users might say, such as 'data warehouse documentation', 'slowly changing dimensions', 'data dictionary', 'curated layer', or 'dbt golden tables'.

Broaden the 'Use when' clause slightly, e.g., 'Use when documenting golden layer tables, curated data models, or when the user asks about SCD documentation, metric definitions, or data quality rules.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: detects SCD types, documents business rules, metric definitions, aggregation logic, and data quality scoring. These are concrete, well-defined capabilities.	3 / 3
Completeness	Clearly answers both what (detects SCD types, documents business rules, metric definitions, aggregation logic, data quality scoring) and when ('Use when documenting golden layer tables') with an explicit trigger clause.	3 / 3
Trigger Term Quality	Includes domain-specific terms like 'golden layer', 'SCD types', 'business rules', 'metric definitions', 'aggregation logic', and 'data quality scoring', but these are fairly technical. Missing common variations a user might say like 'data warehouse documentation', 'dbt docs', 'slowly changing dimensions', or 'data dictionary'.	2 / 3
Distinctiveness Conflict Risk	Highly specific niche targeting 'golden layer' documentation specifically, with distinct domain terminology (SCD types, aggregation logic, data quality scoring) that is unlikely to conflict with general documentation or other data engineering skills.	3 / 3
	Total	11 / 12 Passed

Implementation

14%

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

This skill is extremely verbose, embedding massive documentation templates directly in the SKILL.md rather than referencing separate template files. While it provides a clear output format, it lacks a concrete workflow for how to analyze codebases and extract information, and has no validation checkpoints. The content would benefit enormously from splitting templates into separate files and adding a clear step-by-step analysis workflow.

Suggestions

Extract the large template sections (parent page, attributes page, behaviors page) into separate template files (e.g., TEMPLATE_PARENT.md, TEMPLATE_ATTRIBUTES.md, TEMPLATE_BEHAVIORS.md) and reference them from SKILL.md

Add a clear numbered workflow: 1) Glob for .dig files, 2) Parse workflow structure, 3) Identify SQL files, 4) Extract schema/columns, 5) Detect SCD patterns, 6) Generate documentation - with validation at each step

Include concrete executable examples for codebase analysis, such as specific glob patterns to use, regex patterns for detecting COALESCE/SCD logic, and how to extract line numbers from SQL files

Add validation checkpoints: verify discovered tables match .dig workflow references, confirm all SQL files are parseable, validate attribute counts match between SQL and documentation

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ lines, mostly consisting of a massive template that could be in a separate file. Explains obvious concepts (what golden layers are, what atomic replacement means), and the template itself is largely structural boilerplate that Claude could generate from a much shorter specification.	1 / 3
Actionability	Provides concrete template structures and some SQL examples, but the guidance is more about output format than executable steps. The actual 'how to analyze the codebase' instructions are vague ('Read actual .dig workflows', 'Extract REAL table names') without concrete code or commands for parsing/extracting information from files.	2 / 3
Workflow Clarity	There is no clear sequential workflow for how to actually produce the documentation. The skill jumps from 'verify files exist' to a massive template with no intermediate steps for analysis, extraction, or validation. No checkpoints for verifying extracted data accuracy, no feedback loops for handling missing or unexpected file structures.	1 / 3
Progressive Disclosure	Monolithic wall of text with the entire template inlined in SKILL.md. The massive template sections (parent page, attributes page, behaviors page) should each be in separate reference files. No bundle files are provided despite the content clearly needing them for the extensive templates.	1 / 3
	Total	5 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: treasure-data/td-skills
Commit: 79bb9b8

Reviewed: 2 days 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.