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 guidance with file types and command references. It follows third-person voice and is concise without unnecessary padding.
| 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, configuration) and 'when' with an explicit 'Use when...' clause specifying file types and contexts. | 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, Atlas CLI, HCL schema files) 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 (no progressive disclosure to supporting files) and the lack of an explicit end-to-end workflow with validation checkpoints tying the individual features together. Minor verbosity in some sections could be trimmed.
Suggestions
Add a clear end-to-end workflow section (e.g., 'Making a Schema Change') with numbered steps, explicit validation checkpoints (lint, validate, test), and error recovery guidance.
Split detailed reference content (ORM integration, full linting analyzer list, testing patterns, CI/CD examples) into separate bundle files and reference them from SKILL.md to improve progressive disclosure.
Trim the 'Instructions' section at the end—most of its guidance is already demonstrated by the examples above it, making it redundant.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary verbosity—like the full HCL schema example for orders table which could be trimmed, and the 'Instructions' section at the end restates things already demonstrated. Some sections like 'Two Workflows' and 'Dev Database' are admirably lean. | 2 / 3 |
Actionability | Nearly every section provides fully executable, copy-paste ready code examples—HCL configs, SQL, bash commands, YAML for CI/CD, and test files. Commands include real flags and realistic URLs. This is highly actionable throughout. | 3 / 3 |
Workflow Clarity | While individual commands and features are well-documented, the overall workflow for common multi-step processes (e.g., making a schema change, generating a migration, linting, testing, and applying) is not presented as a clear sequential workflow with validation checkpoints. The 'baseline for existing databases' section has good sequencing, but the general migration workflow lacks explicit validate-then-proceed feedback loops. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers, but it's a monolithic document (~250 lines) with no references to external files. Topics like ORM integration, schema testing, and linting configuration could be split into separate reference files. For a skill of this breadth, inline everything reduces scannability. | 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
aa009ea
- 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.