crystallize
Scannednpx machina-cli add skill rana/yogananda-skills/crystallize --openclawRead all project markdown documents to ground in the project's actual state.
Crystallization Review
Apply the editorial knife across two dimensions: structural simplification and communication quality.
Structural Simplification
- Would you simplify anything? — What's more complex than it needs to be? What's solving a problem that doesn't exist yet?
- Would you remove anything? — What's dead weight? Vestigial decisions? Features that don't earn their keep? Could this be reconstructed from the code and domain knowledge alone — and if so, is it documentation weight masquerading as documentation value?
- Would you restructure anything? — What would be clearer reorganized? What's in the wrong document or section?
- What are you not enthusiastic about? — Where does the design feel forced, over-engineered, or uncertain? Be honest.
- What are you enthusiastic about? — What's working well? What's elegant? Reinforce the strengths.
- Is the design crystalline? — Does every element serve a purpose? Can you see through it clearly?
Communication Quality
- AI readability — Can a fresh Claude session navigate these documents efficiently? Are identifiers unambiguous? Is structure consistent enough for pattern-matching?
- Onboarding — Could a new developer (or a new Claude session) understand the project from docs alone? Where would they get lost?
- Staleness — Are there references to things that no longer exist? Outdated state descriptions? Dead links?
- Redundancy vs. value — Is the same information in multiple places? Is that useful (different audiences need different formats) or dead weight (documentation that exists only because someone wrote it)?
Focus area: $ARGUMENTS
For every proposal:
- What to change and why (the simplification or removal)
- What's preserved (nothing valuable is lost)
- Where the change belongs
Present as an action list. No changes to files — document only.
Output Management
Hard constraints:
- Segment output into groups of up to 8 simplification proposals, ordered by complexity reduction impact.
- Write each segment incrementally. Do not accumulate a single large response.
- After completing each segment, continue immediately to the next. Do not wait for user input.
- Continue until ALL proposals are reported. State the total count when complete.
- If the analysis surface is too large to complete in one session, state what was covered and what remains.
What questions would I benefit from asking?
What am I not asking?
Source
git clone https://github.com/rana/yogananda-skills/blob/main/skills/crystallize/SKILL.mdView on GitHub Overview
Crystallize is the practice of simplifying and sharpening design narratives to remove weight and over-engineering. It targets both structure and communication to ensure clarity and purpose. Grounded in the project’s actual state, it begins with a review of project Markdown docs before proposing focused edits as actionable next steps.
How This Skill Works
It begins by reading all project markdown documents to ground the current state. It then applies a two-dimension editorial lens: structural simplification and communication quality, asking targeted questions about removal, restructuring, and clarity. For every proposal, it documents three elements: what to change and why, what is preserved, and where the change belongs, as an action list (not file edits).
When to Use It
- Designs feel heavy, over-engineered, or accumulated rather than composed.
- Documentation is redundant or dead-weight, with vestigial decisions.
- You need to reconstruct from code and domain knowledge and prune documentation weight masquerading as value.
- Onboarding or new Claude sessions would struggle to understand the project from docs alone.
- Elements lack clear purpose or alignment; you want to sharpen communication and structure.
Quick Start
- Step 1: Read all project markdown documents to ground the actual state.
- Step 2: Apply the crystallization review across structural simplification and communication quality, identifying proposals.
- Step 3: For each proposal, specify what to change, what’s preserved, and where it belongs, and present as an action list.
Best Practices
- Ground the crystallization effort in the current project docs first.
- Separate concerns into structural simplification and communication quality.
- Be brutal about removing dead weight and vestigial decisions.
- Clearly articulate each proposal with what changes, what’s preserved, and where it belongs.
- Present as an action list only; no changes to files during crystallization.
Example Use Cases
- Simplify a monolithic API docs by removing unused endpoints and aligning sections.
- Remove duplicated onboarding guides and harmonize terminology with the codebase.
- Condense a long design doc into concise, purpose-driven sections.
- Eliminate outdated references and dead links in READMEs.
- Restructure a module guide to reflect current architecture and domain concepts.
