Claude Code Skills 완전 가이드

Every Claude Code skill is defined in a SKILL.md file — a Markdown document with optional YAML frontmatter. The frontmatter controls how the skill appears, what tools it can access, and how it executes. The body contains the prompt that Claude follows when the skill is invoked. The minimal SKILL.md requires just a name and a prompt body. As your needs grow, you can progressively add fields: description for autocomplete hints, allowed_tools to restrict capabilities, context to control execution isolation, and invocation to set manual or automatic triggering. The $ARGUMENTS placeholder is central to making skills flexible. When a user types /my-skill some-value, the $ARGUMENTS token in the prompt body is replaced with 'some-value'. This enables parameterized skills that adapt to different inputs without requiring separate skill files for each variation.

Claude Code ships with five official bundled skills that demonstrate best practices and solve common workflows. These skills are maintained by Anthropic and updated with each release. /simplify runs three parallel review agents (code-reuse, code-quality, efficiency) against your changed files, automatically fixing issues it finds. It uses context: fork so each agent gets an isolated view of the codebase. /batch is the powerhouse for large-scale changes. It researches your codebase, decomposes the work into 5-30 independent units, spins up a separate git worktree for each unit, and generates PRs automatically. Ideal for API migrations, code standard enforcement, or cross-cutting refactors. /debug analyzes your session logs to diagnose issues with Claude Code itself — failed tool calls, permission problems, unusual token consumption, or behavioral anomalies. /loop enables repeating tasks with optional cron scheduling. Monitor deployments, run periodic code quality checks, or collect data at intervals. /claude-api provides instant access to Claude API documentation and best practices, helping you build applications that integrate with Claude.

The context field in SKILL.md frontmatter controls execution isolation. With context: share (default), the skill runs in the same context as the main conversation, seeing all prior messages and tool results. With context: fork, the skill gets a clean, isolated context — essential for parallel execution patterns where multiple agents should not interfere with each other. Dynamic context injection via !`command` syntax lets skills pull in runtime information. The command runs before the prompt is sent to Claude, and its output is inlined into the prompt. This is powerful for skills that need to adapt to the current state of the repository, environment, or external systems. The invocation field controls when skills activate. User-invoked skills (invocation: user, the default) require explicit /command calls. Auto-invoked skills (invocation: auto) trigger automatically when certain conditions in the conversation are met — useful for guardrails, linters, or post-action hooks. Combining these patterns enables sophisticated multi-agent workflows. A parent skill can fork multiple child skills, each with its own context, tools, and scope, then collect and merge their results.

Skills follow a clear hierarchy for discovery and organization. Personal skills live in .claude/skills/ (gitignored) or ~/.claude/skills/ (global). Project skills go in your repository root's skills/ directory and are committed alongside code. Plugin skills are distributed via npm packages. Enterprise skills use the Skills API for centralized management. The Agent Skills open standard (agentskills.io) extends SKILL.md to work across multiple AI coding agents. A skill written to this standard can run on Claude Code, Cursor, Windsurf, and other compatible agents. The standard adds version metadata, compatibility declarations, and a registry API. For team deployment, the recommended pattern is a shared skills repository. Teams maintain a central repo of approved skills, which individual projects reference. The $CLAUDE_SKILL_DIR environment variable (v2.1.69+) lets you point to a shared directory of skills without copying files into each project. Organization-level distribution uses the Skills API (/v1/skills) to programmatically list, fetch, and execute skills. This enables CI/CD integration, automated skill updates, and usage analytics across the organization.