postgresql-table-design

I took a look at your postgresql-table-design skill and wanted to share some thoughts.

Links:

• GitHub
• Your skill in the SkillzWave marketplace

The TL;DR

You're at 70/100, which is solid C-grade territory. The skill has real value—your PostgreSQL guidance is genuinely useful, and your examples (users table, orders table, JSONB patterns) actually demonstrate the concepts you're teaching. Strongest area is Utility (17/20), but Progressive Disclosure Architecture (16/30) is dragging the score down significantly.

What's Working Well

• Strong practical examples. Your three SQL examples aren't just syntax dumps—they show real schema decisions (why normalized orders vs. JSONB product variants). That's the kind of thing that actually helps developers think through trade-offs.
• Solid PostgreSQL specificity. You're not generic SQL advice here. Mentions of MVCC, TOAST, HOT, and the MONEY type gotcha show you understand PG quirks that matter.
• Clear Core Rules section. The "Always use", "Prefer", and "Avoid" structure gives developers immediate guidance without having to read a novel first.

The Big One: Progressive Disclosure Architecture

This is your main opportunity. Right now, you're loading all 205 lines into one monolithic SKILL.md file—advanced topics like partitioning, extensions, and JSONB guidance sit alongside table basics. That violates progressive disclosure principles.

The fix: Create a references/ directory with separate files:

• references/data-types.md – Detailed type guidance
• references/indexing.md – B-tree, BRIN, GiST strategies
• references/partitioning.md – Table partitioning patterns
• references/jsonb-guidance.md – JSON column design

Keep SKILL.md focused on the esse...