Optimizing Claude Code Skills: Token Efficiency Through On-Demand Workflows

```html

What Was Done

We refactored the project configuration system by extracting conditional build/deploy commands and architecture patterns from the always-loaded CLAUDE.md file into an on-demand skill. This reduced the core configuration file from ~124 lines to ~57 lines, eliminating ~67 lines (~55%) of unnecessary token consumption on sessions that don't require those workflows.

The Problem: Token Waste in Session Initialization

Every Claude Code session loads CLAUDE.md from the project root, billing tokens for every line. The original file contained:

Lines 56-115 (Per-Project Commands): ~60 lines of build, test, and deployment commands
Lines 117-123 (Architecture Patterns): ~7 lines describing system design patterns
Core content (remaining ~57 lines): Output rules, overview, wiki pointers, required setup, and git repository inventory

The insight: developers use Per-Project Commands and Architecture Patterns only during specific workflows (building, testing, deploying, or exploring design). Most sessions—like code review, documentation work, or debugging—never reference these sections. We were billing tokens for this context on every session, even when unused.

Solution: Skills as On-Demand Context

Claude Code supports Skills.claude/skills/<name>/SKILL.md) or personal scope (~/.claude/skills/<name>/SKILL.md), and load via explicit invocation (/skill-name) or automatic triggering when Claude detects matching request patterns.

We created:

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

This file contains the extracted sections with YAML frontmatter:

--- description: Build, test, deploy commands and architecture patterns for this project ---

The skill auto-triggers when the user's request matches the description (mentions "build," "deploy," "test," or "architecture"), and can also be invoked manually with /project-commands.

Technical Implementation Details

File Structure Changes

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

The new skill consolidates:

Per-project build commands (e.g., npm run build, test runners, linting configs)

Deployment workflows specific to the project stack

Architecture decision records (ADRs) and system design patterns

Modified: CLAUDE.md (from ~124 lines → ~57 lines)

Retained sections in the trimmed file:

Output formatting rules (how Claude should structure responses)

Project overview and context

Wiki and documentation pointers

Required first-run setup steps

Git repository inventory

These sections apply to all sessions, so they justify permanent token cost.

Skill Invocation Patterns

The skill supports two invocation methods:

Automatic: When a prompt mentions "build," "test," "deploy," or "architecture," Claude detects the keyword match against the skill's description and loads it automatically.

Manual: User types /project-commands in any session to explicitly load the skill.

Neither pattern consumes tokens until the skill is actually needed.

Parallel Work: SES Email with PDF Attachment

During the same session, we configured branded email delivery for the JADA platform:

Infrastructure Setup

Service: Amazon SES (Simple Email Service)

Configuration Location: AWS account secrets loaded at session start

Verified Identities: Listed and validated against QDN account SES configuration

Implementation

The workflow:

Load secrets from environment (SES access keys and region)

Download PDF asset from the website (7 pages, ~772 KB)

Construct branded HTML email template with JADA branding

Attach PDF binary data to the email

Send via SES using a verified sender identity

Encoding Bug: Em Dash in From Name

The initial implementation failed when the From name contained an em dash character. SES's MIME encoding was mishandling the special character. The fix:

Replace the em dash with a standard hyphen or remove it

Explicitly encode the From header using RFC 2047 MIME header encoding if special characters are required

Validate the From address format against SES's verified identity list before sending

The corrected implementation now sends successfully with branded JADA branding and the PDF attachment via a verified SES identity.

Token Economics & Architecture Decisions

Why Extract to Skills?

Cost: ~67 lines per session × (estimated 40-50 non-build sessions per week) = 2,680-3,350 token-lines saved weekly per developer.

User Experience: Skills remain contextually available without cluttering the always-loaded configuration. Developers don't need to remember or search through build commands—the skill loads automatically when relevant.

Maintainability: Build and architecture sections can evolve independently. Project commands can be updated without touching the core CLAUDE.md, reducing merge conflict risk.

Skill vs. Hook Decision

We chose Skills over Hooks because:

Hooks fire deterministically on lifecycle events (pre-save, post-command) and always consume tokens

Skills are guidance that Claude interprets only when triggered, making them ideal for optional, context-dependent workflows

Build and deployment commands are inherently optional—not every session needs them

What's Next

Validate the skill auto-trigger: Test that prompts mentioning "build" or "deploy" correctly load the skill without explicit invocation

SES Delivery Monitoring: Set up CloudWatch alarms on SES bounce/complaint rates to catch email deliverability issues early

Extend Skills Architecture: Evaluate other frequently-unused sections of CLAUDE.md or project documentation for extraction into on-demand skills

Document Skill Pattern: Create a reusable template for future skill creation across other projects

Key Takeaway

By treating configuration as two categories—always needed vs. sometimes needed—we reduced token waste without sacrificing context availability. The skill system in Claude Code provides a lightweight mechanism for distributing context on-demand, making it practical to keep comprehensive build