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

Discovery

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 mentions several capabilities, but remains too abstract about concrete actions and lacks explicit trigger guidance. The relationship to 'layer-specific documentation skills' creates potential confusion about when this base skill should be selected versus its dependent skills.

Suggestions

Add an explicit 'Use when...' clause specifying trigger conditions, e.g., 'Use when generating documentation for Treasure Data pipelines, validating doc quality, or publishing pipeline docs to Confluence.'

Clarify the relationship to layer-specific skills by stating when this skill should be chosen instead, e.g., 'Use this for cross-layer documentation tasks; use layer-specific skills for individual layer docs.'

Replace abstract terms like 'shared templates' and 'quality validation' with concrete actions, e.g., 'Generates standardized markdown documentation pages, runs quality checks against style rules, and publishes pages to Confluence spaces.'

Dimension	Reasoning	Score
Specificity	Names the domain (Treasure Data pipeline documentation) and some actions (templates, quality validation, testing framework, Confluence integration), but these are somewhat abstract rather than concrete user-facing actions like 'generates documentation pages' or 'validates markdown structure'.	2 / 3
Completeness	Describes what the skill does (provides templates, validation, testing, Confluence integration) but has no explicit 'Use when...' clause or equivalent trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also somewhat weak, making this a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'Treasure Data', 'pipeline layers', 'Confluence', 'documentation generation', but misses common user variations and natural phrases a user might say (e.g., 'write docs', 'TD docs', 'document my pipeline', 'publish to Confluence').	2 / 3
Distinctiveness Conflict Risk	The mention of 'Treasure Data pipeline layers' and 'Confluence integration' provides some specificity, but the phrase 'used by all layer-specific documentation skills' suggests this is a shared/base skill, which could create confusion about when to use this versus the layer-specific skills it supports.	2 / 3
	Total	7 / 12 Passed

Implementation

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 extremely verbose and tries to be a comprehensive reference document rather than a concise, actionable skill. It contains significant amounts of content Claude already knows (basic SQL, Mermaid syntax, YAML validation), generic templates with placeholders rather than executable examples, and monolithic structure that should be split across multiple files. The core workflow concept is sound but buried under excessive detail.

Suggestions

Split the 60+ quality checks, testing framework, common patterns, and diagram examples into separate reference files (e.g., QUALITY_CHECKS.md, TESTING.md, PATTERNS.md) and link from the main skill

Remove explanations of concepts Claude already knows: basic Mermaid diagram syntax, SQL DESCRIBE commands, YAML validation, ERD notation—just reference them briefly

Replace placeholder SQL ({database}, {table}) with a single concrete end-to-end example showing the full workflow from codebase exploration to published documentation

Condense the three-phase workflow into a tight numbered sequence with explicit validation gates and error recovery steps, removing the YAML pseudocode format

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 60+ quality checks are listed as individual checkboxes that bloat the document enormously. Generic template patterns, placeholder SQL queries, and extensive examples of things like version history tables and security documentation tables add bulk without providing actionable, codebase-specific value.	1 / 3
Actionability	Provides some concrete guidance like Confluence API tool parameters and SQL query templates, but most code examples use placeholders ({database}, {table}) rather than being truly executable. The quality validation checklist is comprehensive but abstract—it lists what to check without showing how to actually perform each check programmatically. Many sections describe what to do rather than providing copy-paste ready commands.	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 validation checkpoint. However, the phases are described in YAML pseudocode rather than executable steps, validation is listed as '60+ checks' without clear sequencing of when/how to run them, and there's no explicit feedback loop for error recovery during the generation process.	2 / 3
Progressive Disclosure	This is a monolithic wall of text with no bundle files to offload content to. The quality validation framework (60+ checks), testing framework (6 test categories), metadata extraction patterns, visual diagram generation, and common patterns sections all belong in separate reference files. The skill references layer-specific skills but doesn't link to any supporting files for its own extensive content. Everything is crammed into one massive document.	1 / 3
	Total	6 / 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: 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.