aps-doc-core

Core documentation generation patterns and framework for Treasure Data pipeline layers. Provides shared templates, quality validation, testing framework, and Confluence integration used by all layer-specific documentation skills.

Quality

30%

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/core/SKILL.md

Quality

Content

27%

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

This skill is a comprehensive but excessively verbose framework document that tries to be both a reference manual and an instructional guide. Its main weakness is extreme length—most of the content (quality checklists, generic Mermaid examples, placeholder SQL, common patterns) should be split into referenced files or eliminated entirely since Claude already knows these concepts. The core workflow is sound but buried under excessive detail.

Suggestions

Extract the 60+ quality checks, testing framework, common patterns, and diagram examples into separate referenced files (e.g., QUALITY_CHECKS.md, PATTERNS.md, TESTING.md) to reduce the main skill to under 100 lines.

Remove generic content Claude already knows: basic Mermaid syntax, SQL DESCRIBE commands, YAML validation via Python, and explanations of what ERD diagrams are.

Replace placeholder SQL ({database}.{table}) with a single concrete, realistic example from an actual Treasure Data pipeline to demonstrate the expected output format.

Integrate validation checkpoints directly into the three-phase workflow rather than listing them as a separate massive checklist—specify which checks apply at which phase with clear pass/fail gates.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~400+ lines. Explains concepts Claude already knows (what Mermaid diagrams are, how YAML validation works, basic SQL patterns). The quality checklist alone is 36 checkbox items that could be a referenced file. Generic template examples, placeholder SQL, and pattern tables add bulk without teaching anything Claude doesn't already know.	1 / 3
Actionability	Provides some concrete guidance (Confluence API tool names/parameters, specific file extensions to look for, SQL query templates), but most code examples use placeholders like {database}.{table} rather than being truly executable. The skill is more of a framework description than copy-paste-ready instructions.	2 / 3
Workflow Clarity	The three-phase workflow (Template Analysis → Codebase Exploration → Documentation Generation) provides a clear sequence, and the mandatory codebase access gate is a good checkpoint. However, validation steps are presented as a massive checklist rather than integrated into the workflow with explicit feedback loops. The 60+ quality checks lack prioritization or clear pass/fail criteria.	2 / 3
Progressive Disclosure	Monolithic wall of text with no bundle files to offload content. The 60+ quality checks, 6 test categories, 4 diagram types, metadata extraction patterns, and common patterns are all inline when they should be in separate referenced files. The skill mentions layer-specific skills but doesn't reference any supporting files for its own detailed content.	1 / 3
	Total	6 / 12 Passed

Description

32%

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 identifies a specific domain (Treasure Data pipeline documentation) and lists several capabilities, but remains too abstract about concrete actions and entirely lacks explicit trigger guidance. Its role as a 'shared framework' skill used by other skills is architecturally interesting but doesn't help Claude know when to select it over the layer-specific skills.

Suggestions

Add an explicit 'Use when...' clause specifying the conditions under which this base skill should be selected instead of (or in addition to) layer-specific documentation skills.

List more concrete actions — e.g., 'Generates documentation pages from pipeline metadata, validates doc completeness against schema, publishes to Confluence spaces' — instead of abstract terms like 'shared templates' and 'quality validation'.

Clarify the relationship to layer-specific skills to reduce conflict risk — e.g., 'Use this skill for cross-layer documentation tasks or when no specific layer skill applies.'

Dimension	Reasoning	Score
Specificity	Names the domain (Treasure Data pipeline documentation) and some actions (templates, quality validation, testing framework, Confluence integration), but the actions are somewhat abstract — 'shared templates' and 'quality validation' lack concrete detail about what specifically is generated or validated.	2 / 3
Completeness	Describes what the skill does (provides templates, validation, testing, Confluence integration) but has no explicit 'Use when...' clause or trigger guidance. The phrase 'used by all layer-specific documentation skills' hints at when, but this describes internal skill architecture rather than user-facing triggers. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also somewhat weak, warranting a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'Treasure Data', 'pipeline layers', 'Confluence', 'documentation generation', but misses common user-facing variations. Terms like 'shared templates' and 'quality validation' are more internal/technical than what a user would naturally say.	2 / 3
Distinctiveness Conflict Risk	The mention of 'Treasure Data pipeline layers' and 'layer-specific documentation skills' provides some niche specificity, but the description positions this as a shared/base framework skill, which could overlap with the layer-specific skills it supports. The boundaries between this and those skills are unclear.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (567 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: treasure-data/td-skills
Commit: adb83d7

Reviewed: 6 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.