How Claude Code’s Skills System Enables AI to Learn Your Workflow

Skills System Overview

A Skill is a structured ability module defined by a SKILL.md file. The core TypeScript definition ( src/skills/bundledSkills.ts) includes fields such as name, description, whenToUse, context (either inline or fork), optional argumentHint, allowedTools, agent, hooks, and an isEnabled flag.

type BundledSkillDefinition = {
  name: string;
  description: string;
  whenToUse: string;
  argumentHint?: string;
  allowedTools?: string[];
  context: 'inline' | 'fork';
  agent?: string;
  hooks?: Hook[];
  isEnabled?: boolean;
};

Skills are loaded from two sources:

Bundled Skills – compiled into the binary via registerBundledSkill() (entry point src/skills/bundled/index.ts).

Disk‑based Skills – user‑defined under .claude/skills/ (or ~/.claude/skills/) and loaded by src/skills/loadSkillsDir.ts. The loader supports three priority layers: managed → user → project.

Disk‑based skills can be conditionally activated with a paths field. For example, paths: ["**/*.py"] restricts activation to Python files, providing finer granularity than always‑on Cursor Rules.

Lazy Extraction

Bundled skill resources (e.g., template SKILL.md files) are stored compressed in the binary. registerBundledSkill() registers a closure that defers decompression until the first invocation. The implementation caches the resulting Promise<string> so concurrent calls share a single extraction.

let cached: Promise<string> | null = null;
function getSkillContent(): Promise<string> {
  if (cached) return cached;
  cached = decompressFromBinary(skillData);
  return cached;
}

This design reduces startup latency, lowers memory usage, and guarantees that parallel requests do not trigger duplicate decompression.

Security Measures

Process‑level nonce protection : getBundledSkillsRoot() uses a nonce to prevent path tampering.

Strict permissions : directories are created with mode 0o700 and files with 0o600.

Symlink guard : files are opened with O_NOFOLLOW | O_EXCL to block symlink attacks.

Path‑traversal guard : resolveSkillFilePath() ensures the resolved path stays inside the skill directory.

Feature‑Flag‑Controlled Grey‑listing

Each skill can be bound to a feature flag (e.g., KAIROS, AGENT_TRIGGERS, BUILDING_CLAUDE_APPS) that gates its availability. Certain commands ( /skillify, /remember, /verify, /stuck) are currently limited to internal users ( USER_TYPE === 'ant').

/skillify – Turning Observation into Reusable Skills

/skillify

is a meta‑skill that watches session memory and user messages, especially corrections, to infer implicit workflow rules. It operates on two input streams:

Session memory – the full conversation history.

User messages – explicit corrections that signal user preferences.

The command runs a four‑round structured interview using the AskUserQuestion interface:

Round 1 – High‑level confirmation : name, one‑sentence description, goal, success criteria.

Round 2 – Detail gathering : step list, required parameters, execution context ( inline vs fork), and storage location (project‑level .claude/skills/ or personal ~/.claude/skills/).

Round 3 – Step breakdown : for each step, ask for output, success standard, checkpoints, parallelizability, execution type, and hard constraints.

Round 4 – Final confirmation : trigger phrase, edge‑case notes, and generate the final SKILL.md.

Why Structured Q&A Instead of Free Chat?

The design enforces three benefits:

Control over dialogue flow to avoid topic drift.

Complete information via checklists, ensuring no step is omitted.

Predictable token consumption because each round has a fixed number of questions.

/simplify – Parallel Multi‑Agent Code Review

The /simplify skill runs a git diff through three parallel agents, each focusing on a distinct dimension:

// Three parallel agents' responsibilities
Agent 1: code‑reuse review – detect existing utilities.
Agent 2: code‑quality review – redundancy, parameter bloat, copy‑paste, abstraction leaks, string misuse.
Agent 3: efficiency review – unnecessary work, missed concurrency, hot‑path bloat, TOCTOU, memory leaks.

After parallel analysis, a “Phase 3” step performs a single, ordered fix‑up to avoid conflicts between agents, embodying the “parallel analysis, serial repair” principle.

/loop and /schedule – From Local Cron to Cloud Scheduler

/loop

implements a local cron with a default 10‑minute interval. Interval parsing follows three priority rules:

1. Explicit token (e.g., "every 5m") → highest priority.
2. Trailing "every" clause (e.g., "check status every 30m") → medium priority.
3. Default value (10 min) → fallback.

Human‑readable tokens like 5m, 1h, 2d are converted to standard cron expressions. To mitigate the thundering‑herd problem, the scheduler adds deterministic jitter (up to 10 % of the interval) and deliberately avoids exact hour marks.

/schedule

runs in Anthropic’s CCR cloud sandbox, persisting tasks to .claude/scheduled_tasks.json. It requires an environment_id (Base58‑encoded mcpsrv_ prefix) that is decoded to a UUID, enabling remote agents to access databases, APIs, and files via MCP connectors. The scheduler enforces a minimum 1‑hour granularity, performs full timezone‑to‑UTC conversion, and supports create, list, update, and run operations (delete is intentionally omitted).

Loop Persistence Modes

session-only

(default) – tasks disappear when the session ends; suited for temporary repetitive actions. durable – tasks are written to .claude/scheduled_tasks.json for long‑running background jobs.

When a task is created, it is executed immediately once, matching user expectations that a newly defined schedule should run at least once before waiting for the next interval.

Additional Built‑In Skills

/debug : tails the last 64 KB of logs, classifies entries by level, and surfaces key errors.

/remember : promotes auto‑memory entries to persistent CLAUDE.md or team memory after verification.

/verify : hooks into code‑change events to run automated validation rules.

/stuck : diagnoses frozen Claude Code sessions (internal‑only).

Agent Types and Permission Model

general

– full tool access; used for general tasks. explore – read‑only search; used for code exploration and information gathering. plan – read‑only analysis; used for architecture planning. verification – code verification; used for regression testing. claudeCodeGuide – help & documentation; used for onboarding and feature lookup. statuslineSetup – UI configuration; used for status bar tweaks.

The hierarchy follows the principle of least privilege: higher‑level agents can do everything, while specialized agents are restricted to their domain, reducing accidental misuse.

Engineering Philosophy Extracted from the Code

Secure‑by‑default : permission bits, nonce checks, symlink guards.

Progressive complexity : single‑run → local cron → remote scheduler, each layer building on the previous.

Least‑privilege design : granular agent types.

Deterministic behavior over randomness : fixed jitter for scheduled tasks.

Comparative Perspective

Key differences compared with other AI‑assisted development tools:

Rule creation : Claude Code can auto‑learn rules via /skillify; Cursor Rules and GitHub Copilot rely on manually written rules or have no rule system.

File format : Skills use a structured SKILL.md schema, whereas other tools use free‑form prompts.

Cross‑tool compatibility : Skills follow the OpenSkills standard, enabling interoperability.

Multi‑Agent support : Six built‑in agent types provide fine‑grained permission control.

Scheduling : Built‑in /loop (local) and /schedule (cloud) give native periodic execution, which is absent in competing products.

Remote execution : CCR cloud sandbox allows agents to run in a managed environment with environment‑ID based access control.

Summary

The Claude Code Skills system demonstrates a shift from passive "you ask, it answers" tools toward proactive agents that observe user behavior, extract reusable workflows, and automate them. The combination of lazy extraction, rigorous security, feature‑flag gating, structured skill authoring, parallel multi‑agent analysis, and progressive scheduling illustrates a design that balances performance, safety, and extensibility. While /skillify is currently internal‑only, the open SKILL.md format and OpenSkills compatibility indicate a strategic move toward industry‑wide standards rather than proprietary lock‑in.