aps-doc-master-segment

Generate Confluence-ready technical documentation for CDP Parent Segments. Produces structured docs covering attribute schemas, behavior definitions, star schema relationships, and data lineage. Use when you need to write docs, create specs, or explain parent segment architecture.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./aps-doc-skills/master-segment/SKILL.md

Quality

Content

56%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 is actionable and well-sequenced with concrete tdx/MCP commands and a clear phased workflow, but it is notably verbose due to repeated fallback instructions and inlines a large template that should be split into a reference file.

Suggestions

Move the full documentation template into a separate reference file (e.g., references/TEMPLATE.md) and replace the inline block with a concise summary plus a link, reducing SKILL.md to an overview.

Consolidate the TD-MCP-vs-tdx fallback instructions into a single section; the current repetition across the MANDATORY block, Phase 1, Phase 2, Summary, and Fallback Strategy is redundant.

Trim repeated emphatic directives ('NO placeholders', 'CRITICAL', 'Period.') to a single statement, since the constraint is already clear from context.

Dimension	Reasoning	Score
Conciseness	The body is noticeably verbose: the TD-MCP-vs-tdx fallback instructions are repeated across the MANDATORY section, Template Usage Notes (Phase 1 and Phase 2), Summary, and Fallback Strategy, and emphatic phrases ('NO placeholders', 'CRITICAL', 'Period.') are restated multiple times.	2 / 5
Actionability	Provides concrete, executable commands ('tdx use database', 'tdx tables', 'tdx describe', 'SHOW TABLES IN', 'DESCRIBE {database}.{master_table}') and a detailed conditional template, with only minor gaps (MCP tool names beyond 'mcp__treasuredata__*' are not enumerated).	4 / 5
Workflow Clarity	Clear phased sequence (Discovery, Schema Extraction, Documentation Generation) with a 'Before proceeding' checklist and a 'STOP if cannot access database' checkpoint; lacks a true validate-fix-retry feedback loop, which keeps it just below 5.	4 / 5
Progressive Disclosure	Has section structure but inlines a ~240-line documentation template that clearly belongs in a separate reference file (e.g., TEMPLATE.md), and no bundle/reference files exist to offload the bulk.	3 / 5
	Total	13 / 20 Passed

Description

87%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.

A strong, specific description that clearly states both capability and trigger conditions with a well-defined niche. The only notable issue is the second-person phrasing in the trigger clause, which slightly lowers the specificity score.

Dimension	Reasoning	Score
Specificity	Lists comprehensive concrete coverage ('attribute schemas, behavior definitions, star schema relationships, and data lineage') plus the action 'Generate Confluence-ready technical documentation', but the trigger clause uses second person ('Use when you need to write docs'), which reduces the score by one per the voice guideline.	4 / 5
Completeness	Clearly answers both what ('Generate Confluence-ready technical documentation for CDP Parent Segments...') and when ('Use when you need to write docs, create specs, or explain parent segment architecture') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural trigger keywords ('write docs', 'create specs', 'explain parent segment architecture') plus niche terms ('Confluence', 'CDP Parent Segments'), but common synonyms like 'document a segment' or 'Confluence page' are missing.	4 / 5
Distinctiveness Conflict Risk	Highly specific niche (CDP Parent Segments, Confluence-ready docs, star schema) with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	18 / 20 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: treasure-data/td-skills
Path: aps-doc-skills/master-segment/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.