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

```html

Session-wide configuration files are convenient but expensive. When your project context file grows to 124 lines and 55% of it is only needed for specific workflows, you're burning tokens on every single session—even the ones that don't need those features. This post walks through how we refactored Queen of San Diego's Claude Code setup to use on-demand skills instead of global configuration, achieving a 55% reduction in CLAUDE.md while maintaining full functionality.

The Problem: Fat Configuration Files

The original CLAUDE.md at the repository root was loaded on every session initialization. It contained three categories of content:

Output Rules (~10 lines): Always needed
Project Overview & Wiki Pointers (~35 lines): Always needed
Per-Project Commands (~60 lines): Only when building/testing/deploying
Architecture Patterns (~7 lines): Only when exploring design decisions
Git Repository List (~12 lines): Occasionally needed

The math: 67 out of 124 lines (~54%) were conditional—useful for maybe 30% of sessions. Every other session was paying token overhead for commands it wouldn't use.

The Solution: Skills as Lazy-Loaded Modules

Claude Code's skills system provides exactly what we needed: reusable, on-demand knowledge that only incurs token costs when invoked or auto-triggered. Skills live at either:

~/.claude/skills/<name>/SKILL.md (personal scope)
.claude/skills/<name>/SKILL.md (project scope)

We created a new project-scoped skill at .claude/skills/project-commands/SKILL.md containing the 60 lines of build, test, and deployment commands. The skill includes a description field that auto-triggers it when Claude detects relevant requests (keywords like "deploy," "test," "build"). Users can also invoke it manually with /project-commands.

Implementation Details

Step 1: Create the Skill Directory Structure

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

Step 2: Define the Skill with YAML Frontmatter

The SKILL.md includes a description field that Claude uses for auto-triggering:

---
description: Build, test, and deployment commands for Queen of San Diego project
---

## Build Commands
...content here...

## Deployment Commands
...content here...

The description is critical: it determines when Claude automatically loads this skill without explicit user invocation. For example, if a user asks "How do I deploy to production?" the skill's description matches, and the skill loads automatically before Claude responds.

Step 3: Refactor CLAUDE.md

The trimmed CLAUDE.md now contains only universally-needed content:

Output formatting rules
Project overview and purpose
Wiki and documentation pointers
Required first-run steps
Git repository listing

Original file: 124 lines → Trimmed: 57 lines. Token savings compound across hundreds of sessions.

Architecture Pattern: Skills vs. Hooks

During this refactor, we clarified the distinction between two Claude Code extension mechanisms:

Skills: Markdown files with optional YAML frontmatter. They're reusable, on-demand guidance that Claude interprets and uses contextually. Zero token cost until triggered.
Hooks: Lifecycle-based enforcement (e.g., before git commit, after file save). They run deterministically and always consume tokens. Use hooks for mandatory validation; use skills for optional workflows.

The Per-Project Commands fit perfectly as a skill because:

Not every session needs them (conditional usage)
They're self-contained workflows (no cross-session state)
Auto-triggering on keyword matches improves UX without clutter
They can be invoked manually with /project-commands when needed explicitly

Why This Matters for Infrastructure

This refactor demonstrates a broader principle in Claude Code workflows: separate concerns by cost and frequency. In the Queen of San Diego project, we're managing:

SES email configuration (verified identities, SMTP endpoints)
S3 bucket paths for static assets and PDFs
CloudFront distribution settings (cache invalidation patterns)
AWS credentials and environment variable management
Project-specific build and deployment targets

By moving project commands to a skill, we reduce noise in the always-loaded configuration. This is analogous to good infrastructure design: don't load environment-specific config until you need that environment.

Practical Impact: Token Budget Example

Assume a 5-day work week with 10 sessions per day (typical development):

Before: 50 sessions × 67 unnecessary lines (~335 tokens per session overhead) = 16,750 wasted tokens weekly
After: 50 sessions × 0 overhead from project-commands + ~50 sessions with auto-triggered skill loads (~10 sessions) × 67 lines (~335 tokens) = 3,350 tokens weekly on project-commands
Weekly savings: ~13,400 tokens (80% reduction on this component)

Over a year, that's ~696,000 tokens freed for actual work—without losing any functionality.

Key Decisions

Project-Scoped Skill: Kept the skill in .claude/skills/ (project root) rather than personal scope (~/.claude/skills/) because these commands are repo-specific. New team members automatically inherit them.
Auto-Triggering via Description: The skill description uses keywords like "deploy," "test," and "build." This provides a good UX: experienced users get the skill silently on relevant requests; newcomers can always invoke /project-commands manually.
Preserving CLAUDE.md: We kept CLAUDE.md lean but present, because it still serves as the project's primary configuration file for always-needed patterns (output rules, overview, repo links). It's now fast to load and read.

What's Next

This pattern can extend to other conditional workflows in the Queen of San Diego codebase:

SES Email Workflows: Move PDF attachment, HTML templating, and verified identity management to a email-operations skill, auto-triggered when requests mention "send," "email," or "PDF"
Infrastructure Patterns: Create a cloudfront-patterns skill for cache invalidation, S3 integration, and CDN troubleshooting
Database Migrations: Separate migration commands from the always-loaded config into a skill that