Every architecture firm has its own way of doing things. Your folder naming convention, your sheet numbering system, your standard detail library, your preferred specification format: these are the patterns that make your practice run smoothly. The problem is that generic AI tools do not know any of this. When you ask Claude Code to “set up a new project,” it has no idea that your firm uses a four-digit project number prefix, organizes Revit models by discipline, or follows a specific sheet index template.

Custom Claude Code skills solve this problem. A skill is a reusable instruction file that teaches Claude Code exactly how your firm operates. Once you build a skill for project setup, code compliance checking, or client communication, every team member can invoke it with a single slash command and get consistent, firm-standard results every time. This tutorial walks you through building these skills from scratch, with complete examples you can copy and adapt today.

---

Why Every Architecture Firm Needs Custom Skills

Architecture firms spend enormous amounts of time on repeatable processes. Consider how many hours per month your team spends on these tasks:

• Project setup: Creating folder structures, naming Revit files, setting up shared parameters, populating title blocks with project information
• Code compliance: Cross-referencing design decisions against IBC, ADA, local amendments, and zoning requirements
• Documentation standards: Formatting specifications, writing drawing notes, creating door and window schedules that match your template
• Client communication: Drafting meeting minutes, writing progress reports, summarizing RFIs, preparing fee proposals

Each of these tasks follows a pattern specific to your firm. A custom skill captures that pattern once and makes it available to everyone on the team instantly. New hires can produce firm-standard output on their first day. Senior staff can skip the repetitive parts and focus on design decisions.

The return on investment is straightforward. If building a skill takes two hours and saves each team member 30 minutes per week, a firm of ten people recovers the investment in the first week. Every week after that is pure time savings.

---

Understanding the Claude Code Skill System

Before you build anything, you need to understand how Claude Code finds and uses skills. The system is simple: skills live in a specific folder inside your project, and each skill is a single markdown file with instructions that Claude Code follows when the skill is triggered.

The directory structure looks like this:

your-project/
├── .claude/
│   └── skills/
│       ├── project-setup.md
│       ├── code-compliance.md
│       ├── client-email.md
│       ├── sheet-index.md
│       └── revit-standards/
│           ├── naming-conventions.md
│           └── family-parameters.md
├── CLAUDE.md
└── ... (your project files)

Key concepts:

• .claude/skills/ directory: This is where all skill files live. Claude Code scans this folder automatically when you start a session.
• SKILL.md or any .md file: Each skill is a markdown file containing instructions. The filename becomes part of how you reference the skill.
• Slash commands: You invoke a skill by typing /skill-name in your Claude Code session. For example, /project-setup would trigger the project-setup.md skill.
• CLAUDE.md: This is your project-level instruction file that Claude Code reads at the start of every session. It can reference skills and set global context.

How Claude Code processes a skill:

1. You type a slash command like /project-setup
2. Claude Code reads the corresponding .md file from .claude/skills/
3. It follows the instructions in that file, using your project files as context
4. It produces output according to the constraints and examples you defined in the skill

The beauty of this system is that skills are plain text files. You can version control them with Git, share them across projects, and edit them in any text editor. There is no proprietary format, no compilation step, and no special tooling required.

---

Step-by-Step: Creating Your First Skill from Scratch

Let’s build a simple skill together. We will create a skill that generates a project brief summary from raw client notes. This is a task every architect does, and the output format is usually firm-specific.

Step 1: Create the skills directory

Open your terminal in your project folder and run:

mkdir -p .claude/skills

Step 2: Create the skill file

Create a new file at .claude/skills/project-brief.md and open it in your text editor. Start with the skill header:

# Skill: Project Brief Generator

## Description
Generate a structured project brief from raw client meeting
notes or email threads. Output follows the firm's standard
brief template.

## Trigger
Use this skill when the user says "generate a brief",
"create a project brief", "summarize client notes into a
brief", or invokes /project-brief.

## Instructions

1. Read the provided client notes or meeting transcript
2. Extract the following information:
   - Project name and address
   - Client name and contact information
   - Project type (new construction, renovation, addition)
   - Approximate square footage
   - Budget range (if mentioned)
   - Key program requirements
   - Site constraints mentioned
   - Timeline expectations
   - Special requirements or concerns
3. Format the output using the template below
4. Flag any critical missing information that needs
   follow-up

## Output Template

### PROJECT BRIEF - [Project Name]

**Date:** [Today's date]
**Prepared by:** [User name if available]

#### Client Information
- **Client:** [Name]
- **Contact:** [Email / Phone]
- **Address:** [Project address]

#### Project Overview
- **Type:** [New Construction / Renovation / Addition]
- **Estimated Area:** [Square footage]
- **Budget Range:** [If provided, otherwise "TBD"]
- **Target Completion:** [Timeline]

#### Program Requirements
[Bulleted list of spaces and requirements extracted
from notes]

#### Site Considerations
[Any site constraints, zoning notes, or environmental
factors mentioned]

#### Open Questions
[List of critical information not found in the notes
that requires follow-up with the client]

## Constraints
- Never fabricate information not present in the source
  notes
- Mark uncertain extractions with "[VERIFY]"
- If budget is not mentioned, write "Not discussed, follow
  up required" instead of guessing
- Use Imperial units unless the project is outside the US

Step 3: Test the skill

Open Claude Code in your project directory and type:

/project-brief

Then paste or reference your client notes. Claude Code will follow the instructions in your skill file and produce a formatted brief.

Step 4: Iterate

After testing, you will likely want to adjust the template, add fields specific to your practice, or refine the extraction instructions. Edit the .md file and test again. Each edit takes effect immediately in your next Claude Code interaction.

---

Anatomy of a Great Skill File

Not all skill files are created equal. A well-structured skill produces consistent, reliable output. A poorly structured one gives you unpredictable results. Here are the sections that make a skill file effective, with explanations of why each matters.

1. Title and Description (required)

Start with a clear # Skill: Name heading and a brief description. This helps Claude Code understand the skill’s purpose and helps your team members browse available skills.

2. Trigger Section (important)

Define exactly when this skill should activate. List the slash command and natural language phrases that should invoke it. Be specific:

## Trigger
Use when the user says "check code compliance",
"verify building code", "is this code compliant",
or invokes /code-compliance. Do NOT trigger for
zoning questions (use /zoning-check instead).

The negative trigger (“Do NOT trigger for…”) is just as important as the positive trigger. It prevents the skill from activating in the wrong context.

3. Instructions (required)

This is the core of your skill. Write step-by-step instructions as if you were training a new employee. Be explicit about the order of operations, what to look for, and how to handle edge cases.

4. Examples (highly recommended)

Include at least one input/output example. This is the single most effective way to get consistent results:

## Example

**Input:** "Client wants a 3-bedroom house, roughly
2000 sqft, modern style, budget around $400k"

**Output:**
### PROJECT BRIEF - [Residential Project]
**Type:** New Construction
**Estimated Area:** 2,000 SF
**Budget Range:** $400,000
...

5. Constraints (important)

Define what the skill should never do. These guardrails prevent common failure modes:

## Constraints
- Never assume occupancy type without explicit information
- Do not reference code sections without verifying the
  edition year
- Always flag life safety items separately from general
  compliance notes
- Output must be in plain English, not legal language

6. References (optional)

Point to external resources, firm standards documents, or other files the skill should consult:

## References
- Firm standard templates: /templates/briefs/
- Project numbering guide: /standards/project-numbers.md
- Client database: check CRM before creating new entries

---

Skill Categories for Architecture Firms

When planning which skills to build, organize them by workflow category. Here are the categories most architecture firms will benefit from, with specific skill ideas for each.

Design Phase Skills:

• Space programming calculator (input room list, output area analysis)
• Massing study brief generator (site constraints into design parameters)
• Precedent study formatter (organize reference projects by relevant criteria)
• Design review checklist generator (phase-appropriate review items)

Documentation Skills:

• Sheet index generator (from model contents and firm standards)
• Drawing note library lookup (search and insert standard notes)
• Specification section drafter (from design decisions to spec language)
• Detail reference finder (match conditions to standard detail library)
• Door/window schedule formatter (from Revit data to firm template)

Coordination Skills:

• RFI drafter (from issue description to formal RFI language)
• Clash report summarizer (from Navisworks export to prioritized action items)
• Consultant coordination checklist (phase-specific items by discipline)
• Submittal log formatter (from raw data to structured tracking document)

Project Management Skills:

• Meeting minutes formatter (from notes to distributed format)
• Fee proposal calculator (from scope description to hour estimates)
• Schedule milestone tracker (extract dates and deadlines from correspondence)
• Change order evaluator (scope change description to cost/time impact)

Quality Control Skills:

• Code compliance pre-check (design parameters against IBC requirements)
• Accessibility audit checklist (ADA/ANSI requirements by space type)
• Drawing QA reviewer (check common errors in documentation sets)
• Energy code preliminary check (envelope and systems requirements)

Start with two or three skills that address your firm’s biggest time sinks. Build those first, test them thoroughly, then expand your library.

---

Example: Building a Project Setup Skill

This is one of the most valuable skills for any firm because project setup happens on every single project and the steps are almost always the same. Here is a complete, production-ready skill file.

Create this file at .claude/skills/project-setup.md:

# Skill: Project Setup

## Description
Initialize a new project with the firm's standard folder
structure, naming conventions, and template files.
Creates all directories and starter files needed for a
new architecture project.

## Trigger
Use when the user says "set up a new project", "create
project folders", "initialize project", "new project
setup", or invokes /project-setup.

## Required Information
Before proceeding, confirm the following with the user:
1. Project number (format: YYYY-NNN, e.g., 2026-042)
2. Project name (short name, no spaces, use hyphens)
3. Client name
4. Project type: NEW, RENO, ADD, INTERIOR, MASTER-PLAN
5. Building type: RESIDENTIAL, COMMERCIAL, INSTITUTIONAL,
   MIXED-USE, INDUSTRIAL

## Folder Structure

Create the following directory tree at the specified
project root:

[ProjectNumber]_[ProjectName]/ ├── 00_ADMIN/ │ ├── Contract/ │ ├── Insurance/ │ ├── Fee_Proposals/ │ └── Project_Info.md ├── 01_PRE-DESIGN/ │ ├── Client_Brief/ │ ├── Site_Analysis/ │ ├── Precedents/ │ └── Zoning/ ├── 02_SCHEMATIC_DESIGN/ │ ├── Sketches/ │ ├── Massing/ │ ├── Presentations/ │ └── SD_Narrative/ ├── 03_DESIGN_DEVELOPMENT/ │ ├── Drawings/ │ ├── Specifications/ │ ├── Renderings/ │ └── DD_Narrative/ ├── 04_CONSTRUCTION_DOCS/ │ ├── Drawings/ │ ├── Specifications/ │ ├── Schedules/ │ └── Details/ ├── 05_BIDDING/ │ ├── Addenda/ │ ├── Bid_Packages/ │ └── Contractor_Quals/ ├── 06_CONSTRUCTION_ADMIN/ │ ├── RFIs/ │ ├── Submittals/ │ ├── Change_Orders/ │ ├── Site_Reports/ │ └── Meeting_Minutes/ ├── 07_CLOSEOUT/ │ ├── Punch_List/ │ ├── As_Builts/ │ └── Warranty/ ├── 08_BIM/ │ ├── Revit_Models/ │ │ ├── [ProjectNumber]_ARCH.rvt (note only) │ │ └── [ProjectNumber]_SITE.rvt (note only) │ ├── Linked_Models/ │ ├── Families/ │ ├── Shared_Parameters/ │ └── BIM_Execution_Plan.md ├── 09_CONSULTANTS/ │ ├── Structural/ │ ├── MEP/ │ ├── Civil/ │ ├── Landscape/ │ └── Specifications/ └── 10_CORRESPONDENCE/ ├── Client/ ├── Consultants/ ├── Contractor/ └── Authorities/

## Template Files to Generate

### Project_Info.md

[Project Number] - [Project Name]

Client: [Client Name] Project Type: [Type] Building Type: [Building Type] Date Created: [Today’s date]

Key Contacts

• Project Architect:
• Project Manager:
• Client Contact:

Project Description

[To be filled in during pre-design]

Key Dates

• Contract Signed:
• SD Complete:
• DD Complete:
• CD Complete:
• Permit Submission:
• Construction Start:
• Substantial Completion:

### BIM_Execution_Plan.md

BIM Execution Plan - [Project Number]

Software

• Primary: Autodesk Revit 2025
• Coordination: Autodesk Navisworks
• Rendering: Enscape / Lumion

File Naming Convention

[ProjectNumber][Discipline][Description].[ext] Example: 2026-042_ARCH_FloorPlans.rvt

Model Organization

• Central model hosted on BIM 360 / ACC
• Local models saved to user machines
• Linked consultant models in 08_BIM/Linked_Models/

Shared Parameters

• Use firm standard shared parameter file
• Located: 08_BIM/Shared_Parameters/

Sheet Numbering

• A0.00 - General / Cover
• A1.00 - Plans
• A2.00 - Elevations
• A3.00 - Sections
• A4.00 - Details
• A5.00 - Schedules / Diagrams
• A6.00 - Interior Elevations
• A7.00 - Reflected Ceiling Plans

## Constraints
- Never overwrite existing project folders
- If a folder already exists at the target location,
  warn the user and stop
- Do not create actual .rvt files (just create a
  README.md noting what Revit files should be created)
- Use underscores in folder names, not spaces
- Project number format must match YYYY-NNN pattern;
  reject invalid formats with a clear error message

## Post-Setup Checklist
After creating the structure, remind the user to:
1. Create Revit central models from firm template
2. Set up BIM 360/ACC project (if applicable)
3. Add project to firm's project tracking spreadsheet
4. Schedule kickoff meeting
5. Distribute Project_Info.md to the team

This skill handles the entire project initialization process that typically takes 30 to 45 minutes of manual folder creation and file copying. With the skill, it takes under a minute.

---

Example: Building a Code Compliance Checker Skill

Code compliance checking is tedious and high-stakes. A missed requirement can mean costly redesign during permitting. This skill does not replace a licensed professional’s judgment, but it serves as a thorough first-pass checklist that catches common oversights.

Create this file at .claude/skills/code-compliance.md:

# Skill: Code Compliance Pre-Check

## Description
Perform a preliminary building code compliance review
based on project parameters. Cross-references IBC 2021
requirements for occupancy, egress, fire protection,
and accessibility. This is a pre-check tool, not a
substitute for professional code review.

## Trigger
Use when the user says "check code compliance", "run a
code check", "IBC compliance review", "pre-check building
code", or invokes /code-compliance.

## Required Information
Gather from the user before proceeding:
1. Occupancy group (A-1 through S-2, or describe use)
2. Construction type (I-A through V-B, or describe)
3. Number of stories above grade
4. Total building area (square feet)
5. Is the building sprinklered? (yes/no)
6. Number of occupants (or describe spaces for calculation)
7. Jurisdiction (state/city for local amendments)

## Analysis Steps

### Step 1: Occupancy Classification
- Confirm occupancy group based on described use
- Check for mixed occupancy conditions
- If mixed, identify whether separated or non-separated
  method applies
- Flag assembly occupancies that may require special
  inspection

### Step 2: Allowable Area and Height (IBC Chapter 5)
- Look up base allowable area for occupancy + construction
  type (Table 504.4)
- Apply frontage increase (if applicable)
- Apply sprinkler increase (if applicable)
- Compare actual area vs. allowable area
- Check allowable stories vs. proposed stories
- Flag any overages with specific code section references

### Step 3: Egress Analysis (IBC Chapter 10)
- Calculate occupant load by space using Table 1004.5
- Determine required number of exits (Table 1006.2.1)
- Check exit width requirements (Section 1005.1)
- Verify travel distance limits (Table 1017.2)
- Check common path of egress travel (Table 1006.2.1)
- Verify dead-end corridor limits (Section 1020.4)

### Step 4: Fire Protection (IBC Chapter 7)
- Identify required fire-resistance ratings for:
  - Structural frame
  - Bearing walls (exterior and interior)
  - Floor assemblies
  - Roof assemblies
- Check fire barrier requirements between occupancies
- Verify shaft enclosure requirements (Section 713)
- Note automatic sprinkler requirements (Section 903)

### Step 5: Accessibility (IBC Chapter 11 + ICC A117.1)
- Verify accessible route from site arrival to building
  entry
- Check accessible entrance requirements
- Identify spaces requiring accessibility compliance
- Note elevator requirements (if applicable)
- Check accessible plumbing fixture counts
- Flag any areas where accessibility exceptions might
  apply

## Output Format

### CODE COMPLIANCE PRE-CHECK
**Project:** [Name]
**Date:** [Today]
**Code:** IBC 2021 (note jurisdiction amendments)

| Category | Requirement | Provided | Status |
|----------|-------------|----------|--------|
| Allowable Area | [X] SF | [Y] SF | PASS/FAIL |
| Allowable Height | [X] stories | [Y] stories | PASS/FAIL |
| ... | ... | ... | ... |

#### Issues Found
1. [Issue description with IBC section reference]
2. [Issue description with IBC section reference]

#### Warnings
1. [Item that needs further investigation]

#### Recommendations
1. [Suggested action to resolve issues]

## Constraints
- Always cite specific IBC section numbers
- Never state compliance definitively; use language like
  "appears to meet" or "may not satisfy"
- Flag any local amendment questions with "VERIFY WITH
  LOCAL JURISDICTION"
- If occupancy group is unclear, present multiple
  interpretations and their implications
- Always include the disclaimer that this is a preliminary
  review and does not replace professional code analysis

This skill turns a complex, multi-chapter code review into a structured process. The output table format makes it easy to track items and share findings with the project team or building officials during pre-application meetings.

---

Example: Building a Client Communication Template Skill

Client communication is one of those tasks that every architect handles slightly differently, but the best firms have a consistent voice and format. This skill ensures professional, thorough client communications regardless of who on the team drafts them.

Create this file at .claude/skills/client-email.md:

# Skill: Client Communication Drafter

## Description
Draft professional client-facing emails and letters
following the firm's communication standards. Covers
project updates, meeting follow-ups, fee proposals,
design approvals, and milestone notifications.

## Trigger
Use when the user says "draft a client email", "write to
the client", "client communication", "meeting follow-up
email", or invokes /client-email.

## Communication Types

### 1. Meeting Follow-Up
**Structure:**
- Thank client for their time
- Summary of key decisions made (bulleted)
- Action items with responsible parties and deadlines
- Next steps and upcoming milestones
- Request confirmation of summary accuracy

### 2. Design Phase Update
**Structure:**
- Current phase status (percentage complete)
- Key progress since last update
- Decisions needed from client (with deadlines)
- Upcoming milestones
- Any budget or schedule impacts to flag

### 3. Fee Proposal Cover Letter
**Structure:**
- Reference to discussed scope
- Brief scope summary (2-3 sentences)
- Attached proposal reference
- Timeline overview
- Invitation to discuss questions
- Next steps if accepted

### 4. RFI to Client
**Structure:**
- Reference to relevant drawing/specification
- Clear statement of question
- Options or recommendations (if applicable)
- Impact of delayed response on schedule
- Response deadline

## Tone Guidelines
- Professional but warm; avoid stiff corporate language
- Use "we" for firm actions, "you" for client actions
- Lead with positive progress before raising concerns
- Be specific about dates and deliverables
- Avoid technical jargon; explain architectural terms
  when necessary
- Keep paragraphs to 3-4 sentences maximum
- Close with a clear call to action

## Constraints
- Never include fee amounts in emails (reference attached
  proposals instead)
- Do not disclose information about other clients or
  projects
- Always include a specific timeline for next steps
- Flag any scope change implications clearly
- Do not promise delivery dates without noting "pending
  team confirmation"

## Example

**Input:** "Write a meeting follow-up for the Johnson
residence. We met Tuesday, decided on the modern
farmhouse direction, they want to add a home office,
budget is tight, need to get back to them on the
addition cost by Friday."

**Output:**
Subject: Johnson Residence - Meeting Summary (March 25)

Dear Mr. and Mrs. Johnson,

Thank you for meeting with us on Tuesday to review the
design direction for your home. It was a productive
session, and we are excited about the path forward.

Here is a summary of the key decisions from our meeting:

- **Design Direction:** We will proceed with the modern
  farmhouse aesthetic as discussed, incorporating the
  board-and-batten siding and standing seam metal roof
  accents
- **Home Office Addition:** You expressed interest in
  adding a dedicated home office to the program; we will
  study how this integrates with the current floor plan
- **Budget Awareness:** We discussed maintaining cost
  consciousness throughout the design process

**Action Items:**
- [ ] Our team: Provide preliminary cost impact of the
  home office addition (by Friday, March 28)
- [ ] Our team: Develop two floor plan options
  incorporating the office (by April 4)
- [ ] Johnson family: Confirm home office size preference
  and any specific requirements (by April 1)

**Next Steps:**
We will present the updated floor plan options at our
next meeting, tentatively scheduled for the week of
April 7. We will coordinate with you on a specific date
once the options are ready for review.

Please review this summary and let us know if we missed
anything or if you would like to clarify any points.

Best regards,
[Architect Name]
[Firm Name]

---

Organizing Skills by Project Phase

As your skill library grows, organizing by project phase keeps things manageable and helps team members find the right skill quickly. Here is a recommended structure that mirrors the standard architectural project phases:

.claude/skills/
├── 00-admin/
│   ├── project-setup.md
│   ├── fee-proposal.md
│   ├── contract-review.md
│   └── project-closeout.md
├── 01-pre-design/
│   ├── project-brief.md
│   ├── site-analysis.md
│   ├── zoning-check.md
│   └── program-analysis.md
├── 02-schematic-design/
│   ├── massing-brief.md
│   ├── design-review-checklist.md
│   ├── presentation-outline.md
│   └── sd-narrative.md
├── 03-design-development/
│   ├── code-compliance.md
│   ├── material-schedule.md
│   ├── consultant-coordination.md
│   └── dd-narrative.md
├── 04-construction-docs/
│   ├── sheet-index.md
│   ├── drawing-notes.md
│   ├── specification-drafter.md
│   └── qa-checklist.md
├── 05-bidding/
│   ├── bid-package.md
│   ├── addendum-drafter.md
│   └── contractor-evaluation.md
├── 06-construction-admin/
│   ├── rfi-drafter.md
│   ├── site-report.md
│   ├── change-order-evaluator.md
│   └── meeting-minutes.md
├── 07-general/
│   ├── client-email.md
│   ├── code-compliance.md
│   └── revit-standards.md
└── README.md

The numbered prefixes mirror the standard project folder structure that most firms already use. Team members intuitively know where to find a skill because it matches their mental model of the project workflow.

The README.md in the skills root is optional but useful. It can list all available skills with one-line descriptions so new team members can quickly see what is available:

# Available Skills

## Admin
- /project-setup - Initialize new project folder structure
- /fee-proposal - Generate fee proposal from scope description

## Pre-Design
- /project-brief - Extract project brief from client notes
- /site-analysis - Organize site analysis findings

## Construction Docs
- /sheet-index - Generate sheet index from Revit model
- /drawing-notes - Look up and insert standard drawing notes

## General
- /client-email - Draft professional client communications
- /code-compliance - Preliminary IBC compliance pre-check

---

Sharing Skills Across a Team

Skills are only valuable at the firm level if everyone can access and use them. Since skills are plain markdown files, sharing them through Git is the natural approach. Here are three strategies, from simplest to most robust.

Strategy 1: Skills in the Project Repo

The simplest approach. Every project repository includes a .claude/skills/ directory. When a team member clones the project, they get all the skills automatically.

Pros: Zero setup, skills travel with the project, version controlled per-project. Cons: Skills are duplicated across projects, updates require manual copying.

Strategy 2: Shared Skills Repository

Create a dedicated Git repository for your firm’s skill library. Each project either clones this repo into its .claude/ directory or uses Git submodules to link it.

# One-time setup: create the shared skills repo
mkdir firm-claude-skills
cd firm-claude-skills
git init
mkdir skills
# ... add your skill files ...
git add .
git commit -m "Initial skill library"
git remote add origin https://github.com/yourfirm/claude-skills.git
git push -u origin main

To use in a project:

# Option A: Git submodule (recommended)
cd your-project
git submodule add https://github.com/yourfirm/claude-skills.git .claude/skills

# Option B: Simple clone (easier, not linked)
cd your-project
git clone https://github.com/yourfirm/claude-skills.git .claude/skills

Pros: Single source of truth, updates propagate via git pull, version controlled. Cons: Requires Git knowledge, submodules add complexity.

Strategy 3: Firm-Level CLAUDE.md with Referenced Skills

Place a CLAUDE.md file at a higher directory level (such as a shared network drive or a parent directory that contains all projects). Claude Code walks up the directory tree looking for CLAUDE.md files, so firm-level instructions automatically apply to all projects within that directory.

/Firm_Projects/
├── CLAUDE.md              (firm-wide instructions)
├── .claude/
│   └── skills/            (firm-wide skills)
├── 2026-042_Johnson/
│   ├── CLAUDE.md          (project-specific overrides)
│   └── .claude/
│       └── skills/        (project-specific skills)
└── 2026-043_Smith/
    └── ...

This layered approach lets you maintain firm-wide defaults while allowing project-specific customization. Project-level skills can override or extend firm-level ones.

---

Testing and Iterating on Skills

Building a skill is only the beginning. The real quality comes from testing and refining based on actual usage. Here is a practical testing workflow.

Step 1: Test with a real scenario

Do not test skills with made-up data. Use an actual past project where you already know what the correct output should look like. This gives you a concrete benchmark.

/project-brief

Here are the notes from the Anderson meeting on March 12:
[paste actual meeting notes from a completed project]

Compare the skill’s output against the brief you actually produced for that project. Note every difference.

Step 2: Test edge cases

Feed the skill incomplete or ambiguous information and see how it handles gaps:

• What happens if the client did not mention a budget?
• What if the project involves mixed use with unclear occupancy classification?
• What if the meeting notes are disorganized or contradictory?

Each failure mode tells you what constraints or instructions to add.

Step 3: Test with different team members

Have two or three people use the same skill independently with the same input. If they get meaningfully different outputs, your instructions are ambiguous. Tighten the language until outputs are consistent regardless of who runs the skill.

Step 4: Track revisions

Use Git commit messages to document what you changed and why:

git add .claude/skills/code-compliance.md
git commit -m "Add mixed occupancy handling to code compliance skill

Previously the skill did not address separated vs
non-separated mixed occupancy. Added Step 1b with
decision criteria based on IBC Section 508."

Step 5: Collect feedback systematically

Create a simple tracking document or shared spreadsheet where team members can log skill issues:

Date	Skill	Issue	Severity	Resolution
4/10	/code-compliance	Missed Type V-B height limit	High	Added Table 504.4 reference
4/11	/client-email	Tone too formal for residential clients	Low	Added residential tone variant

Review this log monthly and batch improvements into skill updates.

---

Advanced Patterns: Multi-Step Skills and Conditional Logic

Once you are comfortable with basic skills, you can build more sophisticated patterns that handle complex, multi-stage workflows.

Pattern 1: Skills That Reference Other Skills

A project kickoff skill can orchestrate multiple other skills in sequence:

# Skill: Project Kickoff

## Description
Run the complete project kickoff workflow by invoking
multiple skills in sequence.

## Instructions

Execute the following skills in order:

1. Run /project-setup to create the folder structure
2. Run /project-brief to generate the initial brief
   from the client's RFP or meeting notes
3. Run /zoning-check if a project address is provided
4. Run /code-compliance with the preliminary occupancy
   and construction type assumptions
5. Compile a summary of all outputs into a single
   "Kickoff Package" document saved to
   00_ADMIN/Kickoff_Package.md

## Output
Save all individual skill outputs in their respective
project folders, then create the combined Kickoff
Package that references each document's location.

Pattern 2: Conditional Logic Based on Project Type

Skills can adapt their behavior based on input parameters:

# Skill: Drawing QA Checklist

## Instructions

Generate a QA checklist appropriate to the project type:

### If project type is RESIDENTIAL:
- Verify room names match program
- Check window sizes against egress requirements
- Confirm garage dimension clearances
- Verify kitchen/bath ventilation notes

### If project type is COMMERCIAL:
- Verify ADA compliance annotations
- Check fire-rated assembly callouts
- Confirm exit signage locations shown
- Verify plumbing fixture count calculations

### If project type is INSTITUTIONAL:
- Include all COMMERCIAL checks above
- Add specialized ventilation requirements
- Check security hardware annotations
- Verify public/private zone separations

### For ALL project types:
- Title block information is complete and current
- North arrow is shown on all plans
- Scale is noted on every drawing
- Drawing numbers match sheet index
- Revision clouds and deltas are current
- Key plan is shown where applicable

Pattern 3: Skills That Generate Other Skills

For firms that want to rapidly build out their library, you can create a meta-skill that helps you write new skills:

# Skill: Skill Builder

## Description
Help the user create a new Claude Code skill file by
interviewing them about the task they want to automate.

## Instructions

1. Ask the user: "What task do you want to automate?"
2. Ask: "Walk me through how you do this task today,
   step by step."
3. Ask: "What information do you need before starting?"
4. Ask: "What does the final output look like? Can you
   share an example?"
5. Ask: "What mistakes should be avoided?"
6. From the answers, generate a complete skill .md file
   with all standard sections (Description, Trigger,
   Instructions, Output Template, Constraints, Example)
7. Save the file to .claude/skills/ with a descriptive
   filename
8. Offer to test the new skill immediately

## Constraints
- Generated skills must include at least one example
- Always include a Constraints section
- Filename should use lowercase-with-hyphens format
- Ask clarifying questions rather than making assumptions

This “skill that writes skills” approach is surprisingly effective. It captures tacit knowledge from experienced team members who may not want to write markdown files themselves but can easily describe their workflow in conversation.

Pattern 4: Phase-Gated Skills with Context Awareness

Skills can check the current project state before executing, preventing common mistakes like running CD-phase checks during schematic design:

# Skill: Phase-Appropriate Review

## Instructions

1. Check for a Project_Info.md file in the project root
2. Read the "Current Phase" field
3. Based on the current phase, run the appropriate review:

   - **SD Phase:** Focus on program compliance, spatial
     relationships, and design intent documentation
   - **DD Phase:** Add material selections, structural
     coordination, and preliminary code compliance
   - **CD Phase:** Full documentation review including
     dimensions, notes, details, specifications, and
     code compliance
   - **CA Phase:** Focus on RFI responses, submittal
     reviews, and field condition documentation

4. If Project_Info.md does not exist or Current Phase
   is not set, ask the user to specify the phase before
   proceeding

---

Getting Started Today

You do not need to build a comprehensive skill library before getting value from this system. Start with one skill. Pick the task your firm does most often, the one where you find yourself explaining the same process to new team members over and over again. Write that process down as a skill file, test it, and refine it.

Here is your action plan for this week:

1. Today: Create the .claude/skills/ directory in one active project
2. Day 1-2: Write your first skill (project setup or client email are great starting points)
3. Day 3: Test the skill with real project data and refine the instructions
4. Day 4: Share the skill with one colleague and get their feedback
5. Day 5: Commit the skill to your project’s Git repository

Once you have one working skill, the next ones come faster. You will start recognizing patterns in your daily work and thinking, “That should be a skill.” Within a month, most firms find they have 8 to 12 skills that meaningfully reduce repetitive work.

The firms that adopt this approach earliest will have a compounding advantage. Every skill you build today makes your team faster tomorrow. And unlike most technology investments in architecture, the cost is just your time writing clear instructions in a text file.

Start with one skill. Test it. Improve it. Then build the next one.