Skip to content

Improve README skill discoverability and layout #421

@howardpen9

Description

@howardpen9

Problem

The current README lists 25+ skills across two tables, but discoverability is poor — it's hard to scan and find the right skill for a given workflow stage. The linear table format buries skills in rows that all look the same, making it difficult for new users to orient themselves quickly.

Specific pain points:

  • No visual hierarchy — all skills appear equal weight, but some (like /office-hours, /qa, /ship) are primary workflow entry points while others are supporting tools
  • Tables don't group by workflow stage — the README describes a "Think → Plan → Build → Review → Test → Ship → Reflect" flow, but the skill table doesn't reflect this structure
  • Hard to scan — 18+ rows of 3-column tables require reading every row to find what you need

Proposal

Reorganize the skill listing to match the sprint lifecycle already described in the README:

  1. Group skills by workflow stage — e.g., under "Think" show /office-hours, under "Plan" show /plan-ceo-review, /plan-eng-review, /plan-design-review, under "Ship" show /ship, /land-and-deploy, etc.
  2. Add visual anchors — use headings or visual separators per stage so users can jump to the stage they're in
  3. Highlight entry points — make it obvious which 3-5 skills a new user should start with (e.g., /office-hours/autoplan/qa/ship)
  4. Consider a quick-reference card — a compact visual (ASCII or simple diagram) mapping the workflow stages to their slash commands at the top, before the detailed tables

Why this matters

gstack's biggest selling point is the opinionated workflow — the README should make that workflow self-evident at a glance, not require reading 25 table rows to piece together.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions