Claude Code Setup Guide: How to Combine Rules, Skills & Workflow

Short answer first: Claude Code configuration is not “dump prompts into one file.” It is four layers with different jobs—CLAUDE.md holds project facts Claude should always know, Rules enforce hard constraints and path-scoped conventions, Skills package reusable multi-step procedures, and Workflow wires Skills, Hooks, scheduled jobs, and CI into something your team can repeat. The most common failure mode is mixing layers: a 40-line deploy checklist in CLAUDE.md burns thousands of tokens every session, or a “no force push” red line buried in a Skill gets forgotten after context compaction.

This guide is for iOS, Flutter, and AI app developers already using or evaluating Claude Code—especially teams thinking about moving their main dev environment to a cloud Mac or remote Mac rental setup. We follow August 2026 official docs and hands-on testing: directory layout, YAML frontmatter examples, a decision table, and notes on running agents long-term on Apple Silicon cloud hardware.

Verified August 6, 2026. Behavior follows the Claude Code Skills documentation and Anthropic’s steering blog; frontmatter fields may shift slightly between releases.

Why layer config instead of one giant CLAUDE.md

Most teams start the same way: Claude Code can read the repo, so put every convention in root CLAUDE.md and call it done. The problem is shared context budget—the more that loads on every session, the less room remains for diffs and tool output. Worse, procedural content (“run tests, bump version, tag, push”) gets mixed with factual content (“main scheme is MyApp-Prod, cert profile is XYZ”), so a small edit in one area ripples everywhere.

In Anthropic’s steering guide, customization splits into seven mechanisms: CLAUDE.md, Rules, Skills, Subagents, Hooks, Output Styles, and system prompt append. For most engineering teams, the first four plus Workflow orchestration cover roughly 90% of needs. If you already run the Cursor + Claude Code + OpenRouter stack, terminal-side layering is analogous to IDE .cursor/rules—but paths and load timing differ, so do not copy-paste blindly.

We saw a typical failure case: a five-person Flutter team stuffed code review checklists, archive steps, and branch policy into CLAUDE.md until the file exceeded 400 lines. Claude carried the entire runbook while tweaking a single widget—responses slowed, and after compaction it often “forgot” test requirements from the back half. Splitting into path-scoped Rules and three Skills cut average input tokens by roughly 30% and reduced review misses.

Core concepts: what each layer solves

CLAUDE.md: the project’s always-on memory

CLAUDE.md (or .claude/CLAUDE.md) loads at every session start. Put short, stable, team-wide facts here:

• One-shot build and test commands (e.g. xcodebuild -scheme MyApp test)
• Monorepo map (apps/ios, packages/core responsibilities)
• Active Skills / Rules index (one-line description + path)
• Summaries of team taboos (details live in Rules)

Official guidance treats this as a readable brief, not a wiki. Past 200 lines, ask whether you accidentally pasted procedures. CLAUDE.md is Claude’s boot checklist, not your internal handbook.

Rules: constraints and path-scoped conventions

Rules are Markdown files under .claude/rules/. Compared to CLAUDE.md:

• They can be path-scoped—load only when editing matching files (e.g. paths: ["**/*.swift"])
• They re-inject after context compaction, which makes them right for security red lines
• Tone is “must / must not,” not “here are 12 suggested steps”

Good Rule content: no committed secrets, Swift naming summary, migrations must be reversible, agents must not run git push --force. Our Black Hat USA 2026 AI Agent security checklist stresses the same point—terminal agent boundaries should be auditable Rules, not hallway agreements.

Skills: reusable procedural playbooks

Skills live in ~/.claude/skills/ (user) or .claude/skills/ (project). Each Skill is a directory with SKILL.md at the core. Per the Skills docs, they use progressive disclosure:

• Session start: only name and description load
• On invocation: full body and bundled scripts load
• Multiple Skills share a token budget; earlier invocations may get evicted

Skill-worthy tasks: TestFlight release checklist, PR review steps, Flutter i18n batch replace, OpenAPI client regen. YAML frontmatter can set allowed-tools (pre-authorized tools), disable-model-invocation: true (manual /skill-name only), context: fork (run in a sub-agent), and more.

Workflow: orchestrating the pieces

Workflow is not a fifth folder—it is how you schedule and trigger the other layers. Hooks run formatters before git commit; cron or launchd calls a /refactor-module Skill overnight; CI runs Claude Code non-interactively for migration scripts; a cloud Mac keeps the same .claude tree via Git. Workflow answers “who triggers which layer, when.”

Combination matrix: what goes where

Hands-on: bootstrap an iOS team config from zero

This layout works in 2–6 person iOS / Flutter mixed repos; trim to fit your team:

your-repo/
├── CLAUDE.md                    # build commands, schemes, skill index
├── .claude/
│   ├── settings.json            # shared team settings (no secrets)
│   ├── settings.local.json      # machine overrides, gitignored
│   ├── rules/
│   │   ├── global-security.md   # block .env reads, no force push
│   │   ├── ios-swift.md         # paths: ["**/*.swift"]
│   │   └── flutter-dart.md      # paths: ["lib/**/*.dart"]
│   └── skills/
│       ├── release-testflight/
│       │   └── SKILL.md
│       └── pr-review/
│           └── SKILL.md

Step 1: write CLAUDE.md (aim for 80–120 lines). Open with a table of schemes, minimum OS, and test entry; add a directory map; close with bullets listing available Skills (name + one line). No step-by-step procedures here.

Step 2: split Rules. Global security in its own file; language norms by path. Example path-scoped frontmatter:

---
paths:
  - "**/*.swift"
  - "**/*.xcodeproj/**"
---

# iOS / Swift constraints
- New UI must include a Preview or explain why not
- Do not change Team ID under Signing & Capabilities
- Network layer changes must update matching unit tests

Step 3: create your first Skill. Start with the highest-frequency, highest-error procedure—often TestFlight release or PR review:

---
name: release-testflight
description: "Archive main scheme and upload to TestFlight; use on release day or when user says 'ship'"
disable-model-invocation: true
allowed-tools: Bash(xcodebuild *) Bash(fastlane *)
---

## Pre-release checks
1. Confirm `main` is merged and CI is green
2. Verify latest `CHANGELOG` entry matches version bump
3. Run `xcodebuild -scheme MyApp -destination 'generic/platform=iOS' archive`
4. Invoke fastlane `upload_testflight` lane
5. Comment build number and processing group on the PR

disable-model-invocation: true means only a manual /release-testflight loads the Skill—Claude will not auto-trigger a release while editing UI. Use this on any sensitive operation.

Step 4: wire Workflow. Configure Hooks in .claude/settings.json (e.g. PreToolUse blocks dangerous commands). On a cloud Mac or local machine, keep the same .claude tree in Git so SSH behavior matches. Team config in the repo; personal API keys and settings.local.json stay gitignored.

Cloud Mac / Apple Silicon: where this config pays off

Claude Code is a terminal agent—execution environment quality determines how much you trust it to run unattended. On VPSSpark-style cloud Mac or remote Mac rentals, layered config delivers three practical wins:

• Environment pinning: bake .claude/, Homebrew deps, and fastlane Ruby versions into the image; swap nodes without re-teaching Skills.
• Stable long sessions: Apple Silicon M4 unified memory handles Xcode, simulators, and Claude Code together; ~4W idle suits overnight /refactor Skills.
• Permission isolation: run agents under a dedicated macOS user on the cloud Mac; Rules block keychain paths—safer than bare-metal on a personal laptop.

Typical Workflow: developer edits in local Cursor → pushes to Git → cloud Mac CI pulls and runs a migration Skill non-interactively → fastlane uploads. Rules stop force push in CI; Skills keep release steps identical to manual runs. Flutter teams can Skill-wrap flutter build ipa and iOS signing under the same security Rules.

If you route API calls through OpenRouter to cut cost, allowed-tools and model choice are independent—but watch memory when sub-agents (context: fork) run in parallel. An M4 16GB node running two fork Skills plus Xcode Archive can hit RAM limits; note in Rules or the Skill that Archive must not overlap a second fork.

Cost, performance, and risk tradeoffs

Token cost: a bloated CLAUDE.md charges a “background tax” every session; Skills save via progressive disclosure, but chaining many Skills in one session competes for the shared budget. Periodically run /context or check official token stats to see which layer dominates.

Maintenance cost: Rules and Skills are versioned and reviewable—cheaper than tribal knowledge—but past ~15 Skills someone should own indexing and retirement, or newcomers cannot find the right one.

Risk: allowed-tools pre-authorization lowers confirmation friction for that Skill turn—enable only on trusted Skills. On shared cloud Mac nodes, isolate personal keys in settings.local.json. Misconfigured Hooks can block commits; test on a branch first.

Compared with explaining everything verbally each session, spending 2–4 hours upfront on layering usually pays back by week three through fewer retries. Compared with dumping everything into CLAUDE.md, layered config keeps long-term token bills and omission rates more predictable. Teams that review their .claude tree quarterly—retiring unused Skills and tightening path scopes—tend to keep gains without config sprawl.

FAQ

Can Claude Code Rules and Cursor Rules be shared?

Conceptually similar, different paths and formats. Cursor uses .cursor/rules; Claude Code uses .claude/rules/. You can maintain one Markdown source and script-sync to both—do not expect automatic interoperability.

Can a Skill call external scripts?

Yes. Put scripts under scripts/ in the Skill directory and reference them in the body; pair with allowed-tools: Bash(./scripts/*) to reduce repeated confirmations. Scripts still need human code review—do not let agents run unaudited shell.

How should teams review new Rules or Skills?

Treat them like code: new .claude/rules/foo.md or skills/bar/SKILL.md in the same PR, human reviewer checks conflicts with security Rules and duplication against CLAUDE.md. Use skillOverrides from the Claude Code Settings docs to disable temporarily without deleting files.

After compaction, Claude forgot Skill steps—what now?

Long sessions may evict earlier Skill content from the shared budget. Mitigations: move critical steps into Hooks (deterministic); have the Skill write a checklist file at the end; keep release Skills behind disable-model-invocation: true and shorter sessions.

I am a solo developer—is this worth it?

Yes, but keep it minimal: a 50-line CLAUDE.md, two Rules (security + language), one Skill for your most repeated task (e.g. /ship). Solo teams iterate fast—15 minutes weekly beats retyping build commands every session.

Summary: sketch the workflow, then write config

Combining Claude Code Rules, Skills, and Workflow is really about modularizing experience. CLAUDE.md answers “what is this project,” Rules answer “what must never happen,” Skills answer “what steps for hard tasks,” and Workflow answers “when does it run automatically.” Clarify the four layers before writing five hundred lines of prompts.

Rollout order we recommend: CLAUDE.md skeleton this week → two security Rules next week → one high-frequency Skill → Hooks on cloud Mac or CI last. After each addition, run a real task and check tokens and miss rate.