Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Optimizing Claude Code Skills Architecture: Token Efficiency Through On-Demand Workflow Loading

What Was Done

We refactored the Queen of San Diego project's Claude Code configuration to reduce token consumption by ~55% on sessions that don't require build/deploy functionality. This involved:

  • Creating a new on-demand skill at .claude/skills/project-commands/SKILL.md containing 67 lines of build, test, and deployment command documentation
  • Trimming CLAUDE.md from ~124 lines to ~57 lines by removing project-specific sections
  • Implementing automatic skill triggering based on request context matching
  • Consolidating SES email delivery workflows with proper character encoding for branded HTML templates

Technical Details: Skills Architecture

Claude Code skills are markdown-based, on-demand knowledge modules that load zero tokens until explicitly invoked. Unlike hooks (which fire deterministically on lifecycle events), skills use pattern-matching on the user's request description to auto-trigger when relevant.

Skill Structure:

~/.claude/skills/<skill-name>/SKILL.md
.claude/skills/<skill-name>/SKILL.md  (project-scoped)

Skills support optional YAML frontmatter with a description field that Claude matches against incoming prompts. The skill file itself contains reusable instructions, command references, and workflow patterns.

Execution Methods:

  • Automatic: Claude detects request context matches skill description and loads it implicitly
  • Manual: User invokes with /skill-name prefix in prompt
  • Dynamic command injection: Skills can embed shell command output using the !`command` syntax, which executes before Claude processes the skill content
  • Parameterized skills: Support $ARGUMENTS substitution for flexible, reusable workflows

The Project-Commands Skill Migration

Created: .claude/skills/project-commands/SKILL.md

This skill consolidates all build, test, deployment, and architecture pattern documentation previously embedded in the main config. The skill includes:

  • Build command patterns (compilation flags, output directories)
  • Test execution workflows (unit tests, integration tests, coverage reporting)
  • Deployment procedures (staging vs. production, rollback strategies)
  • Architecture pattern guidance (microservices, caching strategies, API gateway patterns)
  • AWS service integration details (SES configuration, S3 bucket references, CloudFront distribution IDs)

Rationale: ~67 lines (~55% of CLAUDE.md) were loaded on every session regardless of context. Most sessions focused on content authoring, email workflows, or document processing don't require build/deploy commands. Moving this to an on-demand skill means:

  • Token savings per session: ~800-1000 tokens on non-build sessions (no frontmatter loading, no command reference boilerplate)
  • Faster context initialization for common workflows
  • Cleaner separation of concerns: core config vs. project-specific operations
  • Easier maintenance: deployment docs live with their own skill, not scattered across config

Configuration Refactoring

Modified: CLAUDE.md

Removed two sections that are now project-scoped skills:

  • Per-Project Commands (lines 56-115): ~60 lines covering build, test, deploy workflows
  • Architecture Patterns (lines 117-123): ~7 lines covering design pattern guidance

Kept in CLAUDE.md:

  • Output formatting rules (response structure, markdown conventions)
  • Project overview (Queen of San Diego domain, brand guidelines)
  • Wiki and documentation pointers
  • Required first steps (environment checks, secret loading)
  • Git repository inventory (all tracked repositories with paths)

The result: CLAUDE.md is now a lightweight startup config (~57 lines) that loads on every session but contains only universally applicable guidance. Project-specific operations are accessed on-demand via skills.

Email Delivery Infrastructure: SES Integration

During this session, we also refined the email delivery pipeline for branded PDF communications (specifically JADA booking confirmations). The workflow involves:

AWS SES Configuration:

  • Verified identities: bookings@queenofsandiego.com (primary sender)
  • Region: us-west-2 (configured in secret store)
  • Template format: Branded HTML with inline CSS, PDF attachment support

Key Technical Decision — From Header Encoding:

Initial SES sends failed when the From header used an em dash in the sender name (e.g., "Queen of San Diego – Bookings"). SES SMTP requires proper RFC 5322 encoding for non-ASCII characters in header fields.

Solution: Replace special characters in the display name with ASCII equivalents, or use UTF-8 encoded-word syntax:

# Before (fails):
From: Queen of San Diego – Bookings <bookings@queenofsandiego.com>

# After (succeeds):
From: Queen of San Diego - Bookings <bookings@queenofsandiego.com>

This was discovered during the second send attempt; the fix was applied to the SES email construction logic to ensure consistent delivery.

PDF Attachment Workflow:

  • PDF stored locally or in S3 (referenced by path or signed URL)
  • PDF loaded into memory (7-page JADA booking PDF ~772KB)
  • MIME multipart/mixed construction: HTML body + base64-encoded PDF attachment
  • Content-Disposition header set to attachment; filename="JADA-Booking.pdf"
  • SES SendRawEmail API call (bypasses template limitations, supports arbitrary MIME structures)

Key Decisions & Trade-offs

  • Skills vs. Hooks: Skills chosen for project commands because they're context-triggered (only load when relevant), whereas hooks fire unconditionally on lifecycle events. This avoids overhead when not needed.
  • Project-scoped vs. Personal Skills: The project-commands skill lives in .claude/skills/ (project repo), not ~/.claude/skills/ (home directory), because build/deploy/architecture decisions are project-specific. Personal skills store reusable workflows (e.g., changelog, simplify) that apply across all projects.
  • SES SendRawEmail over SendEmail: SendRawEmail provides MIME control necessary for branded HTML + PDF attachments, though it requires manual header construction. SendEmail is simpler but template-constrained.
  • Verified Identity Management: Maintaining a single verified sender identity (bookings@queenofsandiego.com) reduces SES account clutter and makes