# Author Style Guide

> Create or update the author visual style guide that ensures consistent lighting, color grade, and composition across all author imagery — trigger phrases include "author style guide", "visual style for author", "create style guide", "update style guide", or "ensure image consistency".

- Skill: `joshuashepherd/author-style-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joshuashepherd/author-style-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/author-style-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/joshuashepherd/author-style-guide

---


Define or update the author visual style guide: $ARGUMENTS

$ARGUMENTS should include:
- `create` — Create a new author style guide from reference photos
- `update` — Update an existing style guide with new preferences
- `show` — Display the current style guide
- `apply [image-path]` — Check if an image matches the style guide
- Optionally: reference image paths showing the "look" the user wants
- Optionally: verbal description of desired aesthetic
- Empty — check if a guide exists; if not, start creation

## Purpose

This skill creates a single source of truth — the **Author Style Guide** — stored at
`{{ASSET_DOCS_DIR}}/author-style-guide.md`. Every other asset skill (`/asset-headshot`,
`/asset-hero-portrait`, `/asset-generate`, etc.) checks for this file and follows it
to ensure visual consistency across all author imagery.

Without this guide, each generation is independent and may drift in lighting, color grade,
background treatment, or overall feel. With it, every output matches the established look.

## Before Starting

1. Read `{{CONFIG_PATH}}` for brand identity and existing image URLs
2. Check if `{{ASSET_DOCS_DIR}}/author-style-guide.md` already exists
3. If creating: gather reference images (existing headshots, hero images, or aspirational references)
4. If updating: read the current guide and understand what needs to change

## Style Guide Document Structure

The style guide is a structured markdown document with specific, actionable descriptions
that can be pasted directly into Gemini prompts:

```markdown

# Author Visual Style Guide — [AUTHOR NAME]

## 1. Subject Description

### Physical Description (for Gemini prompt consistency)
[A precise, respectful physical description of the author as they appear in the
reference photos. This ensures Gemini maintains likeness when extending backgrounds
or modifying lighting. Include age range, build, hair, skin tone, and typical
presentation — but only visible, factual attributes.]

Example:
> A man in his early 60s with warm olive-toned skin, short grey-white hair with
> natural texture, trimmed grey beard. Athletic-lean build. Typically wears relaxed,
> thoughtful attire — linen shirts, casual jackets, earth-toned colors. Expressive
> hands, warm and direct eye contact. His presence reads as scholarly yet accessible,
> serious yet warm.

### Expression & Energy
[The default expression/vibe to maintain across imagery]

Example:
> Engaged and warm. A slight, knowing smile — the look of someone who has thought
> deeply about something and is genuinely excited to share it with you. Never stern
> or distant. Never performatively casual. Authentic intellectual warmth.

### Wardrobe Defaults
[What the author typically wears; what looks "right" on them]

Example:
> Earth-toned casual-scholarly: linen shirts in cream, sage, or warm grey. Occasionally
> a casual blazer or lightweight jacket in charcoal or warm navy. Open collar. No ties.
> No logos. The aesthetic is "thoughtful person, not trying too hard."


## 3. Color Grade

### Temperature
> Warm. Always warm. The overall image temperature should lean toward golden/amber.
> Color temperature equivalent: approximately 5200K-5800K (warm daylight to slightly
> warm interior). Never cool, never neutral-clinical.

### Palette Anchors
| Element | Color Reference | Notes |
|---------|----------------|-------|
| Skin highlights | Warm, natural, healthy | Never orange, never grey |
| Skin shadows | Warm brown undertone | Never cold purple or blue |
| Background lights | Amber, honey, cream | {{BRAND_PRIMARY}} to {{BRAND_LIGHT}} range |
| Background darks | Warm charcoal, espresso | {{BRAND_DARK}} to #3D3D3D range |
| Clothing | Earth tones | Sage, cream, warm grey, terracotta |

### Film Reference
> The color grade should feel like: Kodak Portra 400 pushed half a stop — warm,
> slightly desaturated, beautiful skin tones, golden highlights. Not Fuji Velvia
> (too saturated). Not digital-clean. A touch of organic warmth and grain.

### Saturation
> Slightly pulled back from reality. Not desaturated/moody, not hyper-saturated.
> About 85-90% of natural saturation. Colors should feel rich but calm.

### Contrast
> Medium. Not flat, not punchy. Enough contrast to give the image structure and
> dimension, but soft enough to feel inviting. Lifted blacks (darkest point is
> warm charcoal {{BRAND_DARK}}, not pure black).


## 5. Composition Principles

### Framing
> The subject should always have breathing room — not tightly cropped to the edges.
> Minimum 10% of frame as space around the subject in any direction.
> The subject's eyes should be approximately at the upper-third line (rule of thirds).

### Gaze Direction
> Default: looking directly at camera (connection with viewer) OR looking slightly
> toward the text/content zone (guiding the viewer's eye to the message).
> Never: looking away from both camera and content, or looking down.

### Posture
> Relaxed but present. Slight forward lean suggests engagement. Shoulders open,
> not hunched. Hands may be visible and expressive (common in teaching moments)
> but should not be the focus.

### Negative Space
> Always include intentional negative space — for text overlay, for visual rest,
> for editorial balance. The subject should occupy 35-50% of the frame in hero
> images, 60-80% in headshots.


## 7. Reference Prompt Blocks

These are copy-paste-ready blocks for other asset skills to include in their prompts:

### BLOCK: Subject Likeness
```
[Paste the physical description from Section 1. This ensures Gemini maintains consistency
when the source image is not provided as a reference.]
```

### BLOCK: Lighting Setup
```
[Paste the complete lighting profile from Section 2.]
```

### BLOCK: Color Grade
```
[Paste the color grade specification from Section 3.]
```

### BLOCK: Background (Warm Bokeh)
```
[Paste the warm bokeh background description from Section 4.]
```

### BLOCK: Full Style Anchor
```
[Combined blocks 1-4 for complete consistency — use in /asset-series as the style anchor.]
```
```

## Creation Process

### Step 1 — Gather References

Ask the user for:
1. **2-3 existing photos** they consider "on brand" or closest to the desired look
2. **Verbal description** of the look they want (warm? scholarly? approachable? cinematic?)
3. **Anti-references** — what they DON'T want (corporate? cold? over-processed?)
4. **Aspirational references** — other thought leaders, authors, or brands whose visual style they admire

### Step 2 — Analyze Reference Images

Read each reference image and extract:
- Lighting direction, quality, and temperature
- Background type and treatment
- Color palette (dominant colors, shadows, highlights)
- Composition and framing
- Expression and energy
- Overall mood/vibe

### Step 3 — Draft the Style Guide

Write the complete style guide following the structure above. Be specific and actionable —
every description should be precise enough to paste directly into an Gemini prompt.

### Step 4 — Validate with a Test Generation

Generate one test headshot and one test hero using the style guide:

```typescript
import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });

// Load reference image
const refBytes = fs.readFileSync(referenceImagePath);
const refBase64 = refBytes.toString("base64");

// Generate test headshot using style guide blocks
const response = await ai.models.generateContent({
  model: "gemini-2.0-flash-exp",
  contents: [
    {
      role: "user",
      parts: [
        { inlineData: { data: refBase64, mimeType: "image/webp" } },
        {
          text: `Using this reference photo of the subject, create a professional headshot
following this exact style specification:

${STYLE_GUIDE_LIGHTING_BLOCK}

${STYLE_GUIDE_COLOR_GRADE_BLOCK}

${STYLE_GUIDE_BACKGROUND_BLOCK}

Maintain the subject's exact likeness from the reference photo.
Crop: head and upper shoulders, 1:1 aspect ratio.

Generate this as an image.`,
        },
      ],
    },
  ],
  config: { responseModalities: ["image", "text"] },
});
```

### Step 5 — Review & Iterate

Show the test generation to the user:
- Does the lighting match the desired feel?
- Is the color grade right?
- Does the background treatment work?
- Is the overall mood/vibe correct?

Iterate on the style guide until the test generation matches the user's vision.

### Step 6 — Save the Style Guide

Write to `{{ASSET_DOCS_DIR}}/author-style-guide.md`.

## Update Process

When updating an existing style guide:

1. Read the current guide
2. Identify what needs to change and why
3. Update only the affected sections
4. Regenerate a test image to verify the change
5. Save the updated guide with new `updated` date

## Apply / Audit Process

When checking if an image matches the style guide:

1. Read the style guide
2. Read the image to audit
3. Compare against each section:
   - Lighting direction and quality
   - Color temperature and grade
   - Background treatment
   - Subject presentation
   - Composition
4. Score each dimension and report

## Output Format — `create`

```
## Author Style Guide Created

### Author: {{AUTHOR_NAME}}
### File: {{ASSET_DOCS_DIR}}/author-style-guide.md
### Reference Images: 3 analyzed

### Style Summary
- **Lighting**: Warm directional from upper-left, soft fill, subtle rim
- **Color Grade**: Kodak Portra 400 warm, slightly desaturated, lifted blacks
- **Backgrounds**: Warm bokeh study (default), community space, branded gradient
- **Mood**: Scholarly yet warm, authentic, inviting
- **Film Reference**: Portra 400 pushed half stop

### Test Generations
1. Headshot (1:1): {{OUTPUT_DIR}}/style-test/alan-headshot-test.png ✅
2. Hero (16:9): {{OUTPUT_DIR}}/style-test/alan-hero-test.png ✅

### Integration
All asset-* skills will now check for this guide and follow it automatically:
- `/asset-headshot` — lighting, color grade, backgrounds
- `/asset-hero-portrait` — compositions, mood, color treatment
- `/asset-series` — style anchor derived from guide
- `/asset-brand-check` — audit criteria updated to match guide
- `/asset-generate` — brand context informed by guide

### Next Steps
- Review the test generations against your expectations
- If adjustments needed, run `/asset-author-style update`
- Generate your first production headshot with `/asset-headshot`
```

## Output Format — `show`

```
## Author Style Guide — {{AUTHOR_NAME}}

### Quick Reference
| Dimension | Setting |
|-----------|---------|
| Lighting | Warm directional upper-left, soft fill, warm rim |
| Temperature | 5200-5800K (warm daylight) |
| Grade | Portra 400 warm, 85-90% saturation, lifted blacks |
| Default BG | Warm bokeh study (amber/walnut, shallow DOF) |
| Composition | Rule of thirds, eyes at upper third, breathing room |
| Mood | Scholarly, warm, authentic, inviting |

### Reference Prompt Blocks Available
1. `BLOCK: Subject Likeness` — physical description for Gemini consistency
2. `BLOCK: Lighting Setup` — complete 3-point warm lighting spec
3. `BLOCK: Color Grade` — full color treatment spec
4. `BLOCK: Background (Warm Bokeh)` — default background description
5. `BLOCK: Full Style Anchor` — all blocks combined for /asset-series

Use `/asset-author-style show` with `--full` for complete block contents.
```

## Output Format — `apply`

```
## Style Guide Compliance Check

### Image: {{OUTPUT_DIR}}/headshot/alan-instructor.png
### Style Guide: {{ASSET_DOCS_DIR}}/author-style-guide.md

| Dimension | Guide Spec | Image Analysis | Match |
|-----------|-----------|----------------|-------|
| Key light direction | Upper-left, 10 o'clock | Upper-left ✓ | ✅ |
| Light quality | Soft, warm, window-like | Soft ✓, warm ✓ | ✅ |
| Color temperature | 5200-5800K warm | ~5500K estimated | ✅ |
| Skin tone | Warm, natural, healthy | Slightly cool in shadows | ⚠️ |
| Background | Warm bokeh study | Warm bokeh ✓ | ✅ |
| Saturation | 85-90% of natural | ~80% — slightly low | ⚠️ |
| Black point | Warm charcoal, lifted | Pure black in corners | ❌ |
| Expression | Warm, engaged, authentic | Warm, engaged ✓ | ✅ |
| Composition | Rule of thirds, breathing room | Centered — off spec | ⚠️ |

### Overall: 6/9 dimensions match (⚠️ Minor adjustments needed)

### Recommended Edits
1. Warm up shadow areas — shift from cool to warm undertone
2. Lift the blacks — darkest point should be {{BRAND_DARK}}, not pure black
3. Bump saturation slightly — from ~80% to ~87%
4. Reframe slightly off-center using rule of thirds

Use `/asset-edit` with these instructions to bring the image into compliance.
```