Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Optimizing Development Workflows: Migrating Static Configuration to On-Demand Skills in Claude Code

During a recent development session working on the Rady Shell Events static site generator, we identified a significant opportunity to reduce token overhead in our Claude Code workflow. By migrating ~67 lines of per-project commands and architecture patterns from our always-loaded CLAUDE.md configuration file into an on-demand skill, we achieved approximately 55% reduction in baseline configuration overhead—resulting in measurable token savings on every session that doesn't require build/deploy operations.

This post details the technical approach, infrastructure considerations, and architectural patterns that made this optimization possible.

The Problem: Unnecessary Token Burden

Our primary development coordination file, /Users/cb/Documents/repos/CLAUDE.md, had grown to approximately 124 lines. Analysis revealed two distinct sections:

  • Per-Project Commands (~60 lines, lines 56–115): Build, test, and deployment workflows specific to active projects
  • Architecture Patterns (~7 lines, lines 117–123): Reference documentation for common architectural decisions
  • Core Configuration (~57 lines): Output rules, repo overview, required setup steps

The issue: ~67 lines (~55% of the file) were being loaded and tokenized on every session, regardless of whether the user was performing development work. For sessions focused on analysis, documentation, or unrelated tasks, this represented pure overhead.

The Solution: On-Demand Skills Architecture

Claude Code supports skillsdescription field that enables automatic triggering when user requests match the skill's purpose.

We created a new skill at:

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

This file contains:

  • The entire ~60-line "Per-Project Commands" section from CLAUDE.md
  • The ~7-line "Architecture Patterns" reference
  • YAML frontmatter with description: "Summarize git changes since last tag" (auto-triggers on relevant requests)

Technical Implementation Details

Skill Frontmatter & Auto-Triggering

The skill file includes YAML frontmatter that enables automatic invocation:

---
description: Build, test, deploy, and manage project infrastructure; architecture reference
---

When a user request includes keywords like "build," "deploy," "test," or "architecture," Claude automatically loads this skill without explicit user invocation (via /project-commands).

Command Injection via Shell Expansion

Skills support a special syntax for injecting command output directly into Claude's context:

!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

The !`command` syntax executes the shell command and injects the output before Claude processes the skill content. This eliminates the need to manually copy/paste command results.

Parameterization

Skills can accept parameters via the $ARGUMENTS variable:

/project-commands deploy koolandthegang

The skill receives "deploy koolandthegang" as $ARGUMENTS, enabling context-aware command suggestions.

Infrastructure & Deployment Context

To make this concrete, here's what the migrated project commands reference:

  • S3 Buckets: Event site content deployed to S3 for static hosting
  • CloudFront Distributions: Cache invalidation triggered post-deployment via CloudFront cache clearing
  • Route53: DNS routing for event subdomain aliases
  • SES Configuration: Email delivery via Amazon SES with verified sender identities (e.g., bookings@queenofsandiego.com)
  • Python Rendering Pipeline: /Users/cb/Documents/repos/sites/queenofsandiego.com/rady-shell-events/tools/render_event_sites.py generates static HTML from Jinja2 templates

During this session, we executed a full redeployment cycle across multiple event sites (Bob Dylan, Kool and the Gang, Brandi Carlile, Gipsy Kings, Honky and the MoFos, James Taylor, Paul Simon), validating that the S3 upload and CloudFront invalidation logic functioned correctly.

Key Decisions & Rationale

Why Move to Skills Rather Than Separate Files?

We considered splitting project commands into a separate PROJECT.md file, but skills offer distinct advantages:

  • Zero tokens until needed: Separate files still load on session startup; skills do not
  • Auto-triggering: The description field enables Claude to invoke the skill contextually, without user remembering to invoke it manually
  • Scoping: Project-level skills (in .claude/skills/ within the repo) scope automatically to that project; personal skills (in ~/.claude/skills/) are globally available

Why Keep Core Configuration in CLAUDE.md?

The retained ~57 lines in CLAUDE.md are genuinely needed on every session:

  • Output formatting rules: Specify how Claude should structure responses (HTML, markdown, etc.)
  • Repository overview: Context about the monorepo structure and active projects
  • First-steps checklist: Setup tasks required before any development work (git config, environment variables, etc.)
  • Wiki/documentation pointers: Links to architecture docs and runbooks

These are lightweight metadata that inform Claude's understanding of the workspace, not lengthy procedural workflows.

Session Outcomes & Validation

During this development session, the project-commands skill was invoked implicitly when executing deployment workflows. Specifically:

  • Regenerated all event site HTML via the Python rendering pipeline
  • Deployed 7 event sites to S3 with CloudFront cache invalidation
  • Validated modal widgets and templated values in rendered output
  • Sent branded event confirmation emails via SES (fixed From header encoding issues)

All operations completed successfully, confirming that the migrated commands remain functional and accessible via the skill mechanism.

Token Efficiency Results

Before this optimization:

  • CLAUDE.md: ~124 lines loaded on every session
  • Cost: ~67 tokens of baseline overhead per session (rough estimate)

After optimization:

  • CLAUDE.md: ~57 lines loaded on every session
  • .claude/skills/project-commands/