alonso-skills/sql-writing-guidelines
Use when writing or reviewing T-SQL, creating stored procedures, designing table schemas, writing views, building migrations, defining custom types, or architecting a SQL Server application database. Also use when writing RAISERROR patterns, CHECK constraints with scalar functions, base/subtype table hierarchies, composite key designs, role-scoped views with row-level security, or idempotent DDL scripts. If you are touching SQL for an application database, use this skill.
90
90%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
92%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 excels in specificity and trigger term coverage, listing numerous concrete SQL Server patterns and techniques. The explicit 'Use when...' structure clearly communicates both capabilities and activation triggers. The main weakness is the overly broad catch-all statement at the end which could cause conflicts with other database-related skills.
Suggestions
Narrow the final catch-all sentence to be SQL Server-specific, e.g., 'If you are touching T-SQL or SQL Server for an application database, use this skill' to reduce overlap with other database skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: writing T-SQL, creating stored procedures, designing table schemas, writing views, building migrations, defining custom types, RAISERROR patterns, CHECK constraints with scalar functions, base/subtype table hierarchies, composite key designs, role-scoped views with row-level security, idempotent DDL scripts. | 3 / 3 |
Completeness | Clearly answers both 'what' (T-SQL writing, stored procedures, schema design, migrations, etc.) and 'when' with explicit trigger guidance via multiple 'Use when...' clauses and the final catch-all 'If you are touching SQL for an application database, use this skill.' | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: T-SQL, stored procedures, table schemas, views, migrations, custom types, SQL Server, RAISERROR, CHECK constraints, composite key, row-level security, DDL scripts. These are terms a developer would naturally use when seeking help with SQL Server database work. | 3 / 3 |
Distinctiveness Conflict Risk | While it specifies SQL Server and T-SQL which narrows the domain, the broad catch-all 'If you are touching SQL for an application database, use this skill' could overlap with general SQL skills, PostgreSQL skills, or database migration tools. The T-SQL and SQL Server specificity helps but the final sentence widens scope significantly. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-architected skill that covers a comprehensive SQL Server methodology with concrete examples and clear structure. It effectively balances breadth (covering types, transactions, constraints, views, security, queues, migrations, naming, and query patterns) with depth through progressive disclosure to reference files. The main weakness is moderate verbosity — some sections could be tightened without losing clarity, though the content is overwhelmingly domain-specific and actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly efficient and avoids explaining basic SQL concepts, but it's quite long (~300+ lines) with some sections that could be more tightly written. The 'When to Use' section and some prose explanations add moderate verbosity, though most content earns its place as domain-specific methodology. | 2 / 3 |
Actionability | The skill provides concrete, executable SQL examples throughout — CREATE TYPE statements, CHECK constraints with scalar functions, composite key hierarchies, view patterns with WHERE clauses, migration validation queries, and a complete naming convention table. Code is copy-paste ready and specific to SQL Server. | 3 / 3 |
Workflow Clarity | The migration section includes an explicit 4-step validation workflow (run once → verify objects → verify constraints → run again for idempotency). The transaction hierarchy (_trx/_utx/_ut) clearly defines composition patterns. The error handling section specifies explicit control flow with GOTO and @@ROWCOUNT checks after every DML. Destructive operations are well-guarded. | 3 / 3 |
Progressive Disclosure | The skill excels at progressive disclosure — it provides concise overviews of each pattern inline with clear one-level-deep references to dedicated files (references/procedure-structure.md, references/basetype-subtype.md, references/hierarchical-keys.md, etc.). Navigation is well-signaled with descriptive link text throughout. | 3 / 3 |
Total | 11 / 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.
Reviewed
Table of Contents