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.
52
56%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./aps-doc-skills/master-segment/SKILL.mdQuality
Discovery
85%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines a specific niche (CDP Parent Segment documentation for Confluence) with concrete capabilities and explicit trigger guidance. The main weakness is that trigger terms could be broader to capture more natural user phrasings. The description also uses second person ('you need') in the 'Use when' clause, which is a minor voice issue but doesn't significantly harm clarity.
Suggestions
Expand trigger terms to include more natural variations users might say, such as 'segment documentation', 'CDP docs', 'schema documentation', or 'technical spec for segments'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: generating Confluence-ready documentation, covering attribute schemas, behavior definitions, star schema relationships, and data lineage. These are concrete, domain-specific capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('Generate Confluence-ready technical documentation... covering attribute schemas, behavior definitions, star schema relationships, and data lineage') and when ('Use when you need to write docs, create specs, or explain parent segment architecture') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'Confluence', 'docs', 'specs', 'parent segment', 'data lineage', but misses common variations users might say such as 'documentation', 'CDP segments', 'schema docs', or 'technical writing'. The trigger terms are somewhat narrow and domain-specific. | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive due to the specific domain niche of CDP Parent Segments and Confluence-ready documentation. The combination of CDP, parent segments, star schema relationships, and Confluence makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 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 a massive monolithic document that embeds an entire documentation template inline, making it extremely verbose and hard to navigate. While it provides a reasonable workflow structure and some concrete CLI commands, it suffers from heavy repetition (MCP vs tdx fallback explained 3+ times), lacks validation checkpoints, and would benefit enormously from splitting the template into a separate file. The actionable guidance is present but incomplete, with vague MCP tool references and no worked example showing real output.
Suggestions
Extract the documentation template (the ~200-line markdown block) into a separate TEMPLATE.md file and reference it from SKILL.md, reducing the main file to a concise overview with workflow steps.
Eliminate the repeated MCP vs tdx fallback explanations — define the fallback strategy once at the top and reference it thereafter.
Add explicit validation checkpoints: verify table count matches expectations, confirm primary key exists in all tables, validate that schema extraction returned non-empty results before proceeding to documentation generation.
Provide one concrete, complete worked example showing actual MCP tool calls or tdx commands with realistic output, rather than only placeholder-filled templates.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. The massive template is largely self-explanatory boilerplate that Claude could generate from a brief spec. Extensive repetition of 'ONLY if these attribute types exist' patterns, redundant 'CRITICAL' callouts, and the 'When to Use This Skill' section explains obvious things. The Phase 1/2/3 instructions repeat the MCP vs tdx fallback logic three times. | 1 / 3 |
Actionability | Provides concrete tdx CLI commands and MCP tool references, plus a detailed template structure. However, the SQL examples are incomplete (SHOW TABLES but no full extraction queries), MCP tool names are vague ('mcp__treasuredata__* tools'), and the template is filled with placeholders rather than showing a complete worked example with real data. | 2 / 3 |
Workflow Clarity | The three phases (Discovery, Schema Extraction, Documentation Generation) provide a clear sequence, and the MCP vs tdx fallback is well-defined. However, there are no explicit validation checkpoints — no step to verify schema completeness, no check that all tables were discovered, and no error recovery if a table describe fails or returns unexpected results. | 2 / 3 |
Progressive Disclosure | Everything is crammed into a single monolithic file with no references to supporting files. The enormous documentation template (~200 lines) should be in a separate TEMPLATE.md file. The inline template makes the skill extremely hard to scan and navigate. No bundle files exist to offload content to. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- treasure-data/td-skills
- Commit
79bb9b8
- Reviewed
Table of Contents
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.