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

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

Quality

Content

77%

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

The body is highly actionable with executable SQL, diagrams, validation commands, and a well-sequenced three-phase workflow including feedback checkpoints. Its main weakness is conciseness and progressive disclosure: it is a long monolithic file with inline material that would benefit from being split into referenced bundle files.

Suggestions

Move the 60+ quality checks, the standard documentation template, and the testing framework into separate reference files (e.g., QUALITY_CHECKS.md, TEMPLATE.md) linked one level deep from SKILL.md.

Trim the verbose 'MANDATORY codebase access' block and the 'Benefits' bullet lists to the essential gating instruction.

Tighten the metadata-extraction and Confluence sections by removing redundant commentary so every remaining token earns its place.

Dimension	Reasoning	Score
Conciseness	The body contains genuine executable content but is padded with a verbose 'MANDATORY codebase access' block, 'Benefits' lists, and a full inline 60+ item checkbox checklist, fitting anchor 2 rather than the lean anchor 3.	2 / 3
Actionability	Provides executable SQL (DESCRIBE, volume-metrics), Mermaid diagrams, bash validation (yaml.safe_load, grep for placeholders), and specific Confluence MCP tool/parameter names that are copy-paste ready, matching anchor 3.	3 / 3
Workflow Clarity	A clear three-phase sequence is paired with explicit validation/testing checkpoints, a STOP-if-no-files gate, and a quality checklist with feedback loops, matching anchor 3.	3 / 3
Progressive Disclosure	Sections are well organized but the ~560-line body is monolithic with no references, and content that should be split (60+ checks, standard template, testing framework) is inline; the under-50-line exception does not apply, so anchor 2.	2 / 3
	Total	10 / 12 Passed

Description

50%

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 communicates the skill's domain and component capabilities but omits an explicit trigger ('Use when…') clause, capping completeness and trigger quality at 2. It is specific enough to avoid being generic but could conflict with the layer-specific skills it underpins.

Suggestions

Add an explicit 'Use when…' clause naming natural trigger phrases (e.g., 'Use when creating custom Treasure Data pipeline documentation or extending layer-specific doc skills').

Reframe the opening from abstract 'patterns and framework' into concrete actions (e.g., 'Generates, validates, and publishes Confluence documentation for Treasure Data pipeline layers').

Clarify the boundary versus the layer-specific skills so this core is less likely to trigger when a user wants ingestion/staging/golden docs specifically.

Dimension	Reasoning	Score
Specificity	Names the domain and concrete components ('shared templates, quality validation, testing framework, and Confluence integration') but leads with abstract 'patterns and framework' rather than a list of concrete action verbs, matching anchor 2 rather than 3.	2 / 3
Completeness	Clearly states what the skill provides but offers no explicit 'when to use' trigger clause; per the guidelines a missing 'Use when…' caps completeness at 2.	2 / 3
Trigger Term Quality	Contains relevant natural terms ('documentation', 'Confluence', 'templates', 'Treasure Data pipeline layers') but lacks a 'Use when…' trigger framing and common variations, fitting anchor 2.	2 / 3
Distinctiveness Conflict Risk	The Treasure Data pipeline documentation niche is fairly distinct, but as a shared 'core' it overlaps with the five layer-specific skills it feeds, matching anchor 2.	2 / 3
	Total	8 / 12 Passed

Validation

93%

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 — 15 / 16 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	15 / 16 Passed

Repository: treasure-data/td-skills
Commit: 50d5a57

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