developer-ai 1.0.0

package/skills/human-like-coding/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: human-like-coding
+description: Guide AI agents to write code that feels human-crafted rather than AI-generated. Use this skill when building websites, UIs, or any frontend code that should avoid the telltale signs of AI generation. Applies principles of intentional imperfection, personal voice, narrative flow, and authentic design decisions.
+---
+
+# Human-Like Coding Skill
+
+This skill teaches AI agents how to write code that feels authentically human-crafted, avoiding the common patterns and fingerprints that make AI-generated code obvious.
+
+## Objective
+
+Design and develop websites that feel human-made rather than AI-generated. Avoid predictable SaaS patterns, generic copy, and over-polished layouts.
+
+## Structured Layout Rules
+
+### Avoid:
+- Perfect symmetry everywhere
+- 3-column feature grid by default
+- Hero → Features → Testimonials → Pricing → FAQ pattern
+- Centered hero text every time
+- Uniform 8px spacing system across everything
+
+### Prefer:
+- Asymmetric layouts
+- Offset sections
+- Mixed alignment (left hero instead of centered)
+- Occasional irregular spacing (18px, 37px, 23px etc.)
+- Section width variations
+- Intentional white space
+
+---
+
+## Overview
+
+AI-generated websites and code have clear fingerprints. This skill helps you create work that feels genuinely human by understanding what makes code feel human vs machine-generated.
+
+**Core Principle:**
+AI optimizes for completeness and symmetry.
+Humans optimize for expression and intent.
+Design for feeling, not for structure.
+
+## What Makes Code Feel Human-Coded
+
+### 1. Intentional Imperfections (Visual Tension)
+
+**Human developers:**
+- Break spacing rules slightly
+- Use inconsistent border radii sometimes
+- Mix font weights imperfectly
+- Don't always follow perfect grid symmetry
+- Developer personality
+- Honest trade-offs discussion
+
+**AI patterns to avoid:**
+- "Welcome to our innovative platform"
+- "We deliver cutting-edge solutions"
+- "Seamless experience"
+- Generic startup tone
+
+**Avoid these overused words:**
+- Seamless
+- Innovative
+- Cutting-edge
+- Next-generation
+- Revolutionary
+- Empowering
+- Clean but sterile layouts
+
+**Principle:** Humans create *visual tension*. AI creates *visual balance*.
+
+### 2. Personal Voice & Microcopy
+
+**Human sites have:**
+- Weird small jokes in footer
+- Conversational copy
+- Unexpected phrases
+- Emotional sentences
+- Real-world context and metaphors
+
+**AI patterns to avoid:**
+- "Welcome to our innovative platform"
+- "We deliver cutting-edge solutions"
+- "Seamless experience"
+- Generic startup tone
+- Overusing words: "Seamless", "Innovative", "Next-generation", "Cutting-edge", "Empowering", "Revolutionary"
+
+### 3. Layout Flow That Breaks Patterns
+
+**Human designers:**
+- Use overlapping sections
+- Break container width mid-page
+- Add unexpected empty space
+- Use staggered grids
+- Add slightly rotated elements
+- Create experimental scroll effects
+- Use custom separators like waves instead of lines
+- Create unique cursor pointers on interactive elements
+
+**AI patterns to avoid (the standard template):**
+1. Hero
+2. Features grid (3 columns)
+3. Testimonials
+4. CTA
+5. Footer
+
+Same order. Every time.
+
+### 4. Real Constraints & Tradeoffs
+
+**Human projects show:**
+- Slight performance compromises
+- Uneven icon styles
+- Mixed illustration styles
+- Weird design decisions driven by time constraints
+- Unfinished features/roadmap items
+
+**AI patterns to avoid:**
+- Over-polished everything
+- Too consistent styling
+- Every icon same72px+)
+- Small body text (14px)
+- Play with line height creatively
+- Strong contrast in font scale
+
+**AI patterns to avoid:**
+- Safe SaaS typography scale (16px base, 1.5 line height, 32px headings)
+- Always using Inter, Poppins, or Roboto
+- Very predictable type scales
+- Uniform hierarchy
+- Use dramatic font-size jumps
+- Big hero text (96px+)
+- Small body text (14px)
+- Play with line height creatively
+
+**AI patterns to avoid:**
+- Safe typography (16px base, 1.5 line height, 32px headings)
+- Always using Inter, Poppins, or Roboto
+- Very predictable type scales
+
+### 6. Color Behavior
+
+**AI patterns to avoid:**
+- Soft gradients everywhere
+
+---
+
+## Styling Standards
+
+### Avoid:
+- `border-radius: 12px` everywhere
+- Subtle `box-shadow` on every card
+- Glassmorphism by default
+- Purple-blue gradients
+- OTechnical Signals
+
+### Avoid:
+- Over-perfect component structure
+- Excessive abstraction
+- Over-commenting obvious code
+- Everything perfectly modularized
+- No visible decision-making
+
+### Prefer:
+- Practical structure with real trade-offs
+- Visible decision-making in comments
+- Realistic trade-offs discussion
+- Developer notes showing thought process
+- Some code left slightly less organized (but functional)
+### Avoid:
+- Feature listing without narrative
+- Generic testimonials
+- Placeholder avatars
+- Fake metrics
+- Hero with gradient background → 3-column features → Testimonials → CTA → Footer (the template)
+
+### Prefer:
+- Story-driven scroll flow
+- Problem → Frustration → Solution → Outcome narrative
+- Real constraints and trade-offs
+- Roadmap or unfinished ideas section
+- Behind-the-scenes content
+- Architecture diagrams
+- Technical blog section
+- How it works internally explanations
+- Purple-blue combos
+- Glassmorphism
+- Glow effects
+- Pastel SaaS palette
+- Following trends too closely
+
+**Human color choices:**
+- Sometimes ugly but bold colors
+- High contrast
+- Unexpected palettes
+- Brand personality over trends
+
+## Common AI Fingerprints to Remove
+
+### Layout Patterns
+- Hero with gradient background
+- Centered headline
+- 3-column features
+- Rounded cards with consistent radii
+- Subtle hover lift animation
+- CTA button with gradient
+- Footer with 4 columns
+
+### Styling Patterns
+- `border-radius: 12px` everywhere
+- Subtle `box-shadow` everywhere
+- `backdrop-blur` overuse
+- Glassmorphism panels
+- Fade-in animations on scroll
+- Smooth scroll always enabled
+- Intersection observer reveal animations
+
+### Component Patterns
+- Card grid layouts
+- Pricing table (3 tiers)
+- FAQ accordion
+- Testimonial slider
+- Navbar with blur background
+- Sticky header
+- "Get Started" primary CTA
+
+### Animation Patterns (Too Predictable)
+- Fade up on scroll (`opacity: 0 → 1`)
+- `translateY(20px)` on entrance
+- `hover: scale(1.05)`
+- Button ripple effects
+
+## What AI Usually Misses
+
+### 1. Narrative Flow
+- Humans tell a story across scroll
+- AI lists features
+- **Fix:** Structure as: Problem → What sucks → What I built → Why it matters
+
+### 2. Emotional Intent
+**Humans design for:**
+- Feeling
+- Frustration resolution
+- Aspiration
+- Humor
+
+**AI designs for:**
+- Structure
+- Completeness
+
+### 3. Strategic White Space
+- AI fills space
+- Humans leave emptiness intentionally
+
+### 4. Personality Through Constraints
+**Human projects sometimes:**
+- Only use 2 colors
+- Use no animation
+- Go brutalist style
+
+AI tries to impress always.
+
+### 5. Unexpected Decisions
+**Human choices:**
+- Left-aligned hero instead of centered
+- Asymmetric layout
+- Hard cut sections
+- Mixed dark/light sections
+
+**AI choices:**
+- Balanced, centered, safe
+
+## How To Make It Look Human
+
+### Break Symmetry
+- Offset images
+- Shift elements slightly off-grid
+- Mix alignment (don't center everything)
+
+### Add Voice
+- Add 2-3 personal lines
+- Add weird/quirky footer text
+- Include real developer notes
+- Show personality in microcopy
+
+### Remove Some Polish
+- Don't animate everything
+- Use sharp edges sometimes
+- Mix in subtle imperfections
+- Leave some rough edges intentionally
+
+### Tell a Story
+Instead of listing features:
+```
+Feature 1, Feature 2, Feature 3
+```
+
+Structure as:
+```
+Here's the problem
+Here's what sucks about current solutions
+Here's what I built
+Here's why it matters
+```
+
+### Add Human Touches
+- Technical blog section
+- "How it works internally"
+- Architecture diagrams
+- Real dev notes
+- P
+
+### Variable Naming
+- Use slightly longer, more descriptive names
+- Include occasional comments that show thought process
+- Don't over-comment everything perfectlyerformance tradeoffs discussion
+- Roadmap with unfinished items
+- Custom cursors on interactive elements
+- Unique animations (not just fade/slide)
+- Wave separators instead of lines
+- Custom SVG illustrations
+
+## Code Style Guidelines
+
+### Variable Naming
+- Use slightly longer, more descriptive names
+- Include occasional comments that show thought process
+- Don't over-comment everything perfectly
+
+### Structure
+- Leave some code slightly less organized
+- Mix patterns occasionally (consistency but not robotic)
+- Include TODO comments for future improvements
+
+### CSS/Styling
+```css
+/* Human Signals Checklist
+
+Verify your work has these signals that it was human-made:
+
+- [ ] Slight asymmetry exists in layout
+- [ ] Copy contains personality and avoids generic startup buzzwords
+- [ ] Layout breaks at least one common SaaS pattern
+- [ ] Some intentional asymmetry (offset sections, mixed alignment)
+- [ ] Typography has character and dramatic size contrasts
+- [ ] Colors aren't the "safe" AI palette (avoid soft pastels unless intentional)
+- [ ] Animations are selective and meaningful, not on every element
+- [ ] There's narrative flow, not just feature lists
+- [ ] Strategic white space/emptiness used intentionally
+- [ ] Personal touches visible (quirky copy, developer notes, comments)
+- [ ] Not everything is perfectly polished
+- [ ] At least one unexpected element exists
+- [ ] Spacing isn't perfectly systematic (mix 18px, 37px, 23px vs pure 8px grid)
+- [ ] No generic testimonials or placeholder avatars
+- [ ] Real constraints or roadmap discuss
+// Human: Casual, shows thinking
+// this fixes that weird Safari bug from 2019
+// TODO: probably should refactor this mess later
+
+// AI to avoid: Too formal and complete
+// This function handles the Safari browser compatibility
+// issue related to flexbox rendering in version 12.1
+```
+
+## Example Transformations
+
+### Before (AI-like)
+```html
+<section class="features">
+  <div class="feature-card">
+    <h3>Seamless Integration</h3>
+    <p>Our cutting-edge solution provides...</p>
+  </div>
+</section>
+```
+
+### After (Human-like)
+```html
+<section class="features" style="padding: 67px 0 89px;">
+  <div class="feature-card" style="border-radius: 8px 12px 8px 14px;">
+    <h3>It just works with your stuff</h3>
+    <p>Plug it in, grab coffee, come back. Done.</p>
+  </div>
+</section>
+```
+
+## Summary Checklist
+
+When generating code, verify:
+
+- [ ] Spacing isn't perfectly systematic
+- [ ] Copy has personality and avoids buzzwords
+- [ ] Layout breaks expected patterns somewhere
+- [ ] Some intentional asymmetry exists
+- [ ] Typography has character
+- [ ] Colors aren't the "safe" AI palette
+- [ ] Animations are unique or minimal
+- [ ] There's narrative flow, not just feature lists
+- [ ] Some strategic emptiness/white space
+- [ ] Personal touches are visible (comments, quirks)
+- [ ] Not everything is perfectly polished