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

57%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./aps-doc-skills/core/SKILL.md

Quality

Content

60%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 body is rich, actionable, and well-sequenced with strong validation scaffolding, but it is a monolithic 560-line document that ignores progressive disclosure and carries some dramatic padding plus a redundant summary.

Suggestions

Split the monolith into bundle files — move the Standard Documentation Template to references/template.md, the 60+ quality checks to references/quality-checks.md, and the Confluence integration params to references/confluence.md — leaving SKILL.md as an overview with one-level-deep pointers.

Remove the dramatic 'MANDATORY: Codebase Access Required...Period.' framing and the closing Summary section, which restates capabilities already detailed in the body; replace with a concise gate statement.

Either replace the {database}.{table} placeholder SQL with a worked real example, or explicitly justify the templating convention, since the skill's own 'NO placeholders' mandate currently contradicts its examples.

Dimension	Reasoning	Score
Conciseness	Most of the body is efficient structured guidance, but padded sections remain — the dramatic 'WITHOUT codebase access = NO documentation. Period.' framing and the closing Summary that re-lists every capability already covered in the body could be trimmed.	3 / 5
Actionability	Concrete, executable material is abundant — real MCP tool names (mcp__atlassian__createConfluencePage) with parameter blocks, validation bash (python3 -c yaml.safe_load, grep for placeholders), Mermaid syntax, and SQL patterns — with only minor gaps from pervasive {database}.{table} placeholders.	4 / 5
Workflow Clarity	A clear three-phase workflow (Template Analysis → Codebase Exploration → Generation) is paired with an explicit codebase-access gate ('STOP if cannot read files'), a 60+ check validation list, and a 6-test testing framework; the only gap is that 'if validation fails, fix and re-validate' feedback loops are implied rather than as explicit as the anchor-5 example.	4 / 5
Progressive Disclosure	The 560-line body is a single monolithic file with no references/, scripts/, or assets/ bundle, and large reference-style blocks (the full standard template, the 60+ checks, Confluence integration params, four common patterns) that clearly belong in separate files are inlined.	2 / 5
	Total	13 / 20 Passed

Description

55%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 conveys what the core framework provides but omits explicit trigger guidance and does not disambiguate itself from its five sibling skills. It reads as a domain statement rather than an invocation trigger.

Suggestions

Add an explicit 'Use when...' clause naming concrete trigger situations, e.g. 'Use when generating Treasure Data pipeline documentation, extending layer-specific doc skills, or building custom Confluence documentation workflows.'

Disambiguate from sibling skills in the description itself — state that this is the shared core and point users to specialized skills for standard layer types, so the core is not triggered when a specialized skill fits.

Soften internal jargon ('pipeline layers', 'layer-specific documentation skills') with more natural synonyms a user might actually say, such as 'pipeline documentation', 'Confluence docs', or 'data pipeline runbooks'.

Dimension	Reasoning	Score
Specificity	Names the domain ('Core documentation generation patterns and framework for Treasure Data pipeline layers') and several concrete capabilities ('shared templates, quality validation, testing framework, and Confluence integration'), but they are framework-level deliverables rather than the concrete user-facing actions that would warrant a 5.	4 / 5
Completeness	It clearly answers 'what' the skill provides, but offers no 'Use when...' clause or equivalent trigger guidance — 'used by all layer-specific documentation skills' describes audience, not when Claude should invoke it, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Relevant domain keywords appear ('documentation', 'Confluence', 'Treasure Data pipeline layers'), but the phrasing leans on internal jargon ('layer-specific documentation skills', 'pipeline layers') and lacks natural synonyms or variations a user would naturally say.	3 / 5
Distinctiveness Conflict Risk	It is niched to Treasure Data pipeline documentation, but explicitly overlaps with five sibling layer-specific skills (ingestion, hist-union, staging, id-unification, golden) without clarifying when to pick this core skill over a specialized one.	3 / 5
	Total	13 / 20 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
Path: aps-doc-skills/core/SKILL.md
Commit: ff38137

Reviewed: 1 day 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.