atlas-best-practices
Patterns for Atlas database schema management covering HCL/SQL schema definitions, versioned and declarative migrations, linting analyzers, testing, and project configuration. Use when working with atlas.hcl, .hcl schema files, Atlas CLI commands, or database migrations.
88
82%
Does it follow best practices?
Impact
97%
1.10xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Quality
Discovery
100%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 well-crafted skill description that clearly identifies the tool (Atlas), lists specific capabilities (schema definitions, migrations, linting, testing, configuration), and provides explicit trigger conditions with natural keywords. It follows the recommended pattern of 'what it does' followed by 'Use when...' and uses third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: HCL/SQL schema definitions, versioned and declarative migrations, linting analyzers, testing, and project configuration. These are concrete, identifiable capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (schema management covering HCL/SQL definitions, migrations, linting, testing, project config) and 'when' (explicit 'Use when working with atlas.hcl, .hcl schema files, Atlas CLI commands, or database migrations'). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'atlas.hcl', '.hcl schema files', 'Atlas CLI commands', 'database migrations', 'HCL', 'SQL', 'linting', 'schema definitions'. Good coverage of both tool-specific and general terms. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with Atlas-specific terminology (atlas.hcl, HCL schema files, Atlas CLI) that clearly distinguishes it from generic database or migration skills. Unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and highly actionable Atlas reference with excellent executable examples covering schema definitions, migrations, linting, testing, and CI/CD. Its main weaknesses are the monolithic structure that could benefit from progressive disclosure via linked sub-files, and the lack of explicit validation checkpoints and error recovery loops in multi-step migration workflows. Minor verbosity could be trimmed without losing clarity.
Suggestions
Add explicit validation/feedback loops to the versioned migration workflow, e.g., 'Run atlas migrate lint -> fix issues -> re-lint -> only then apply' with clear checkpoint markers.
Split detailed sections (Schema Testing, ORM Integration, Migration Linting configuration) into separate referenced files and link from SKILL.md to reduce monolithic length.
Remove the opening sentence explaining what Atlas is—Claude can infer this from context—and trim filler phrases to improve token efficiency.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanations (e.g., 'Atlas is a language-independent tool for managing database schemas' and minor filler phrases). The content is comprehensive but could be tightened in places—some sections like the full HCL schema example are quite long when shorter snippets would suffice. | 2 / 3 |
Actionability | Excellent actionability throughout—nearly every section includes fully executable CLI commands, complete HCL configurations, SQL examples, and YAML CI configs. The code is copy-paste ready with realistic values and covers the full range of Atlas operations. | 3 / 3 |
Workflow Clarity | The two workflows (declarative vs versioned) are clearly distinguished, and the baseline adoption process has a clear sequence. However, there are no explicit validation checkpoints or error recovery feedback loops in the migration workflows—e.g., no 'validate before applying' step or 'if lint fails, fix and re-lint' loop for the versioned migration workflow, which involves potentially destructive database operations. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers, but it's a monolithic document (~250 lines) that could benefit from splitting detailed sections (schema testing, ORM integration, linting configuration) into separate referenced files. No external file references are provided despite the content's breadth. | 2 / 3 |
Total | 9 / 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
- NeverSight/skills_feed
- Commit
e437c3c
- 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.