name: markdown-design description: Create distinctive, visually striking GitHub profile READMEs and markdown documents with exceptional design quality. This skill should be used when the user asks to create or improve a GitHub profile README, personal portfolio in markdown, or any markdown document that requires high visual impact. Generates creative, polished markdown that avoids generic templates and AI-generated aesthetics.

Markdown Design

This skill guides creation of distinctive, museum-quality GitHub profile READMEs and markdown documents that transcend generic templates. Craft markdown as a visual medium with exceptional attention to aesthetic details, typographic choices, and compositional balance.

The user provides markdown requirements: a GitHub profile README, portfolio section, project showcase, or documentation page. They may include context about personal brand, technical focus, or aesthetic preferences.

Design Philosophy Creation

Before writing markdown, establish a VISUAL PHILOSOPHY for the document:

Name the aesthetic direction (1-2 words): "Terminal Elegance" / "Geometric Precision" / "Organic Flow" / "Brutalist Code" / "Minimalist Craft"

Articulate the philosophy through:

• Spatial Rhythm: How negative space, section breaks, and visual breathing room create hierarchy
• Typographic Voice: How headers, emphasis, and text treatments express personality
• Visual Language: How badges, icons, stats, and decorative elements form a cohesive system
• Compositional Balance: How asymmetry, alignment, and flow guide the reader's eye
• Craftsmanship: Every element must appear meticulously placed, as if labored over for hours

CRITICAL: The final work must look like it took countless hours to create—the product of someone at the absolute top of their field with painstaking attention to every detail.

Design Thinking

Understand context and commit to a BOLD aesthetic direction:

• Purpose: What impression should this README create? What story does it tell?
• Audience: Who visits this profile? Recruiters, collaborators, open-source community?
• Tone: Pick an extreme—brutally minimal, maximalist showcase, retro-terminal, organic/natural, luxury/refined, playful/creative, editorial/magazine, geometric/precise, soft/approachable, industrial/utilitarian
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity.

Markdown Aesthetics Guidelines

Typography & Text Treatments

• Headers: Use hierarchy intentionally. Mix # levels with purpose. Consider decorative separators.
• Emphasis: Strategic use of bold, italics, and inline code as visual accents
• Blockquotes: Use > for visual emphasis, philosophical statements, or highlighted content
• Lists: Curated bullet points with consistent rhythm. Avoid walls of undifferentiated items.

Visual Elements (GitHub-Compatible)

• Badges: Curate thoughtfully—quality over quantity. Group by category. Use shields.io with consistent styling (flat, flat-square, for-the-badge, plastic). Custom colors matching the overall palette.
• GitHub Stats Cards: Integrate github-readme-stats, streak-stats, or trophy displays. Customize themes to match aesthetic direction.
• Icons & Emojis: Use sparingly as visual anchors. Consistent style (outline vs filled). Consider emoji as typographic elements.
• Dividers: Creative separators using ---, decorative ASCII, or subtle patterns
• Images & GIFs: Header banners, animated elements, or visual showcases. Ensure they serve the narrative.

Spatial Composition

• Negative Space: Generous breathing room between sections. Dense content feels overwhelming.
• Alignment: Left-aligned text is readable. Centered elements create visual anchors.
• Flow: Guide the eye through intentional section ordering
• Grid Thinking: Use HTML tables for multi-column layouts when pure markdown falls short

Color & Theme Coherence

• Badge Palettes: Consistent color families across all shields.io badges
• Stats Themes: Match card themes (dark, radical, tokyonight, etc.) to overall aesthetic
• Contrast: Dark mode and light mode considerations—GitHub respects prefers-color-scheme

Advanced Techniques

• HTML Integration: <div align="center">, <img alt="markdown-design image"> with sizing, <details> for collapsibles
• ASCII Art: Minimal, tasteful use for personality without overwhelming
• Animated Elements: Typing SVGs, animated stats, or subtle GIF accents
• Tables: Clean data presentation with consistent formatting

Anti-Patterns to Avoid

NEVER create generic markdown with these hallmarks of "AI slop":

• Overused badge walls without curation or visual hierarchy
• Default shields.io colors without customization
• Cookie-cutter section ordering (About → Skills → Projects → Contact)
• Generic greetings ("👋 Hi there, I'm...")
• Walls of undifferentiated text or bullet points
• Mismatched visual styles (mixing badge types, inconsistent icons)
• Cluttered layouts without breathing room
• Templates that could belong to anyone

Craftsmanship Mandate

IMPORTANT: Match implementation complexity to the aesthetic vision.

• Maximalist designs: Elaborate layouts, custom badges, animated elements, layered visual systems
• Minimalist designs: Restraint, precision, careful attention to spacing, typography, and subtle details

Elegance comes from executing the vision well. Every element must be placed with the precision of a master craftsman.

Output Format

Produce markdown that:

1. Renders beautifully on GitHub's markdown parser
2. Works in both dark and light mode
3. Is cohesive with a clear aesthetic point-of-view
4. Feels genuinely designed for the individual's personal brand
5. Could be shown as evidence of design expertise

Remember: Claude is capable of extraordinary creative work. Push beyond convention, commit fully to a distinctive vision, and create something that proves markdown can be an art form.