Claude Code is Anthropic's agentic coding tool that lives in your terminal. It reads your codebase, edits files, runs commands, and handles git workflows through natural language. But its real power emerges when you teach it how your team works — through skills.
\nSkills are markdown-based playbooks that extend what Claude Code can do. Instead of explaining the same workflow every session — how to deploy, how to write commit messages, how to review PRs — you write it once as a skill, and Claude follows it consistently. With over 77,000 GitHub stars and adoption across the developer community, Claude Code has become a central tool in many development workflows. In this post, we’ll explore how skills work, how to create your own, and the patterns that make them effective.
\nBefore diving into skills, let’s establish what Claude Code brings to the table. It’s an agentic coding assistant that operates directly in your terminal. Start it in any project directory:
\nclaudeFrom there, you interact through natural language. Ask it to refactor a function, fix a bug, explain a piece of code, or create a pull request. What makes it “agentic” is that it doesn’t just suggest — it acts. A single request can trigger dozens of independent tool calls: reading files, searching code, editing multiple files, running tests, and committing changes.
\nKey capabilities include:
\nClaude Code also reads CLAUDE.md files at the start of every session. These project-level configuration files tell Claude about your architecture, coding standards, build commands, and conventions. Think of CLAUDE.md as the persistent context and skills as the on-demand playbooks.
Skills are the mechanism for teaching Claude Code how to handle specific tasks. Each skill is a directory containing a SKILL.md file — a markdown document with frontmatter metadata and natural language instructions.
The key insight is how skills are loaded. At startup, Claude only reads the name and description of each available skill. The full instructions are loaded into context only when a skill is actually invoked. This progressive disclosure keeps context usage efficient — you can have dozens of skills installed without paying a context cost for all of them.
\nSkills can be invoked two ways:
\n/skill-name in the conversationThis dual invocation model means skills can serve as both explicit commands and background knowledge that Claude draws on when appropriate.
\nSkills can be defined at three levels, each scoped differently:
\n| Level | \nPath | \nApplies To | \n
|---|---|---|
| Personal | \n~/.claude/skills/<name>/SKILL.md | \nAll your projects | \n
| Project | \n.claude/skills/<name>/SKILL.md | \nThis project only | \n
| Plugin | \n<plugin>/skills/<name>/SKILL.md | \nWhere the plugin is enabled | \n
Personal skills are great for workflow preferences that follow you across projects — your preferred commit message format, your code explanation style, your deployment checklist. Project skills encode team conventions — API patterns, testing requirements, review processes — and are committed to version control so every team member benefits.
\nIn monorepo setups, Claude automatically discovers skills from nested .claude/skills/ directories when you work in subdirectories. A packages/frontend/.claude/skills/ directory is picked up when you’re working in that package.
A skill is a directory with at minimum a SKILL.md file. The file uses YAML frontmatter followed by markdown instructions:
---\nname: review-component\ndescription: Reviews React components for accessibility, performance,\n and adherence to project conventions. Use when reviewing PRs or\n checking component quality.\n---\n\nWhen reviewing a React component, check the following areas:\n\n## Accessibility\n- All interactive elements have appropriate ARIA attributes\n- Images have alt text\n- Color is not the only means of conveying information\n- Keyboard navigation works correctly\n\n## Performance\n- No unnecessary re-renders (check dependency arrays)\n- Large lists use virtualization\n- Images are optimized and lazy-loaded\n\n## Conventions\n- Component uses TypeScript with proper prop types\n- Follows the project's naming conventions\n- Uses Tailwind utility classes (no inline styles)\n- Tests cover the main interaction paths\n\nProvide specific line references for any issues found.The frontmatter controls how the skill behaves:
\n---\nname: deploy-production\ndescription: Deploys the application to production. Runs tests,\n builds the Docker image, and pushes to the container registry.\ndisable-model-invocation: true\nuser-invocable: true\nallowed-tools: Read, Grep, Glob, Bash\nargument-hint: \"[environment]\"\nmodel: claude-sonnet-4-20250514\n---The most important fields:
\nname: The slash command name. Lowercase, numbers, and hyphens only (max 64 characters). Defaults to the directory name if omitted.description: What the skill does and when to use it (max 1024 characters). This is what Claude reads at startup to decide relevance, so write it carefully.disable-model-invocation: Set to true to prevent Claude from automatically invoking this skill. Essential for skills with side effects like deployments or sending messages.user-invocable: Set to false to hide from the / menu. Useful for background skills that Claude invokes on its own.allowed-tools: Which tools Claude can use without asking permission during skill execution. Restrict to Read, Grep, Glob for read-only skills.argument-hint: Shows during autocomplete to guide usage, like [branch-name] or [issue-number].model: Override the model for this skill. Use a faster model for simple tasks, a more capable one for complex analysis.The invocation control matrix gives you fine-grained control:
\n| Configuration | \nUser Can Invoke | \nClaude Can Invoke | \n
|---|---|---|
| Default (no flags) | \nYes | \nYes | \n
disable-model-invocation: true | \nYes | \nNo | \n
user-invocable: false | \nNo | \nYes | \n
Skills support variable substitution for arguments passed during invocation:
\n---\nname: fix-issue\ndescription: Reads a GitHub issue and implements the fix\nargument-hint: \"[issue-number]\"\n---\n\n## Issue Context\nRead GitHub issue #$ARGUMENTS and understand the problem.\n\n## Implementation\n1. Find the relevant code\n2. Implement the fix\n3. Write tests\n4. Create a commit with message: \"fix: resolve #$ARGUMENTS\"Invoking /fix-issue 42 replaces $ARGUMENTS with 42 throughout the skill.
For more powerful context injection, skills support the !`command` syntax, which runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder:
---\nname: pr-summary\ndescription: Summarizes the current pull request\ncontext: fork\nagent: Explore\n---\n\n## Pull Request Context\n- Changed files: !`gh pr diff --name-only`\n- PR description: !`gh pr view --json body -q .body`\n- Review comments: !`gh api repos/{owner}/{repo}/pulls/{number}/comments`\n\n## Task\nSummarize this pull request. Focus on:\n1. What changed and why\n2. Any concerns raised in review comments\n3. Suggested improvementsThis is incredibly powerful. The skill dynamically fetches live data — the actual PR diff, comments, and description — and hands it to Claude as context. Every invocation works with current data, not stale instructions.
\nFor tasks that benefit from isolation, skills can run in a forked context:
\n---\nname: deep-research\ndescription: Performs thorough codebase research on a topic\ncontext: fork\nagent: Explore\n---\n\nResearch the following topic in this codebase: $ARGUMENTS\n\nTrace through all relevant code paths. Map the architecture.\nIdentify patterns, abstractions, and dependencies.\nReturn a comprehensive summary with the 10 most important\nfiles to understand this area of the codebase.The context: fork setting runs the skill in an isolated subagent. The subagent has access to the codebase and tools but not the conversation history. This prevents research tasks from consuming your main context window.
Built-in agent types include Explore (optimized for codebase navigation), Plan (for architecture design), and general-purpose (full capabilities). You can also define custom agents in .claude/agents/ for specialized workflows.
While a single SKILL.md is sufficient, skills can include supporting files:
review-security/\n├── SKILL.md # Main instructions\n├── owasp-checklist.md # Reference material\n├── examples/\n│ ├── good-review.md # Example of expected output\n│ └── bad-review.md # Example of what to avoid\n└── scripts/\n └── scan.sh # Script Claude can executeReference files provide detailed context that Claude loads as needed. The SKILL.md stays concise with instructions, while owasp-checklist.md contains the full reference. This separation keeps the primary skill lean while making deep knowledge available.
For strict output formatting, use a template file:
\n<!-- template.md -->\n## Security Review: {{component_name}}\n\n### Summary\n{{one_paragraph_summary}}\n\n### Findings\n{{findings_table}}\n\n### Risk Level\n{{low|medium|high|critical}}\n\n### Recommended Actions\n{{numbered_action_items}}Reference the template from your SKILL.md:
Format your output according to the template in template.md.\nFill in all placeholder fields.Claude Code ships with several built-in skills that demonstrate the pattern:
\n/simplify: Reviews recently changed files for code reuse, quality, and efficiency. Spawns three parallel review agents and aggregates findings./batch <instruction>: Orchestrates large-scale changes across a codebase. Decomposes work into independent units, spawns background agents in isolated git worktrees, implements changes, runs tests, and opens PRs./loop [interval] <prompt>: Runs a prompt repeatedly on a schedule. Useful for monitoring deploys or polling for status changes.These bundled skills are good reference implementations for your own skills. They demonstrate patterns like parallel agent spawning, work decomposition, and iterative execution.
\nHere are skills that solve common development workflow problems:
\n---\nname: commit\ndescription: Creates a conventional commit from staged changes.\n Analyzes the diff, determines the commit type, and writes a\n descriptive message.\ndisable-model-invocation: true\n---\n\nCreate a git commit following the Conventional Commits specification.\n\n## Steps\n1. Run `git diff --staged` to see what's being committed\n2. Analyze the changes to determine the type:\n - `feat`: New feature\n - `fix`: Bug fix\n - `refactor`: Code restructuring\n - `docs`: Documentation only\n - `test`: Adding or updating tests\n - `chore`: Maintenance tasks\n3. Write a commit message: `type(scope): description`\n - Scope is the primary area affected (component name, module)\n - Description is imperative mood, lowercase, no period\n - Add a body if the \"why\" isn't obvious from the diff\n4. Include `Co-Authored-By: Claude <noreply@anthropic.com>`\n5. Show the message and ask for confirmation before committing---\nname: create-component\ndescription: Generates a new React component with TypeScript,\n tests, and Storybook story following project conventions.\nargument-hint: \"[ComponentName]\"\n---\n\nGenerate a new React component named `$ARGUMENTS`.\n\n## File Structure\nCreate these files:\n- `src/components/$ARGUMENTS/$ARGUMENTS.tsx`\n- `src/components/$ARGUMENTS/$ARGUMENTS.test.tsx`\n- `src/components/$ARGUMENTS/$ARGUMENTS.stories.tsx`\n- `src/components/$ARGUMENTS/index.ts` (barrel export)\n\n## Component Conventions\n- Use TypeScript with an exported Props interface\n- Use `forwardRef` for components that render DOM elements\n- Use Tailwind CSS for styling (no CSS modules)\n- Include JSDoc comment on the Props interface\n- Export as named export, not default\n\n## Test Conventions\n- Use Vitest and Testing Library\n- Test rendering, interaction, and edge cases\n- Use `screen` queries, not container queries\n\n## Story Conventions\n- Use CSF3 format with `satisfies Meta<typeof Component>`\n- Include `tags: ['autodocs']`\n- Create stories for: Default, WithProps, EdgeCase---\nname: explore\ndescription: Read-only codebase exploration. Use when you want to\n understand code without risk of modifications.\nallowed-tools: Read, Grep, Glob\ncontext: fork\nagent: Explore\n---\n\nExplore this codebase to answer: $ARGUMENTS\n\nYou are in read-only mode. Search files, read code, and trace\nthrough execution paths. Do not suggest changes — focus entirely\non understanding and explaining what exists.\n\nReturn:\n1. A clear explanation of what you found\n2. Key files involved (with paths and line numbers)\n3. Architecture diagram in ASCII if applicableCLAUDE.md and skills serve complementary roles. The CLAUDE.md file is loaded into context at the start of every session — it’s the persistent project knowledge. Skills are loaded on demand — they’re the task-specific playbooks.
A well-structured setup looks like:
\nproject/\n├── CLAUDE.md # Project context (always loaded)\n├── .claude/\n│ └── skills/\n│ ├── commit/SKILL.md # Commit workflow\n│ ├── review-pr/SKILL.md # PR review process\n│ └── create-component/SKILL.md # Component scaffoldingYour CLAUDE.md defines the “what” — project architecture, coding standards, key commands. Skills define the “how” — step-by-step workflows for specific tasks. When a skill runs, CLAUDE.md is also loaded alongside it, so skills always have project context available.
Generate an initial CLAUDE.md by running /init in Claude Code. It analyzes your codebase and produces a starting point that you can refine over time.
Each skill should do one thing well. A “deploy-and-notify-and-update-docs” skill should be three separate skills that can be composed. Small, focused skills are easier to test, maintain, and reuse.
\nThe description is the most important field in your frontmatter. Claude uses it to decide when a skill is relevant, so be specific about both what the skill does and when to use it:
\n# Bad\ndescription: Helps with components\n\n# Good\ndescription: Generates a new React component with TypeScript,\n tests, and Storybook story. Use when creating new UI components\n or when the user asks to scaffold a component.Keep SKILL.md under 500 lines. Move detailed reference material to separate files within the skill directory. Structure your content as: metadata (~100 tokens), instructions (<5000 tokens), and resources (loaded as needed). Every token in a skill is a token that can’t be used for reasoning about your code.
Any skill that has side effects — deploying, sending messages, deleting resources — should set disable-model-invocation: true. This ensures it’s only run when you explicitly type the slash command, not when Claude decides it might be helpful:
---\nname: deploy\ndescription: Deploys to production\ndisable-model-invocation: true\n---Skills that work well with Claude Opus might need more detail for Sonnet or Haiku. Test your skills across models and adjust the level of instruction detail accordingly. You can even set a specific model per skill using the model field.
Skills follow the Agent Skills open standard, which works across multiple AI tools including Cursor, Gemini CLI, and Codex CLI. Writing skills to this standard means they’re portable — a skill you write for Claude Code can work in other tools that support the specification.
\nSkills transform Claude Code from a general-purpose assistant into a tool that knows your team’s specific workflows. The combination of CLAUDE.md for persistent context and skills for on-demand playbooks creates a development environment where Claude understands not just your code, but how your team works with it.
Start small — pick one repetitive workflow you explain to Claude regularly and encode it as a skill. As your skill library grows, you’ll find that the consistency and time savings compound. Every new team member benefits from the same encoded knowledge, and every session starts with Claude already knowing how you work.
\nThe skills system is an open standard, meaning the investment you make in writing skills pays off across tools, not just Claude Code. That portability, combined with the progressive disclosure architecture that keeps context usage efficient, makes skills one of the most practical ways to customize your AI development workflow.
\n‘Till next time!
","rawMarkdownBody":"\n## Teaching Your AI Coding Partner New Tricks\n\nClaude Code is Anthropic's agentic coding tool that lives in your terminal. It reads your codebase, edits files, runs commands, and handles git workflows through natural language. But its real power emerges when you teach it how your team works — through skills.
\n\nSkills are markdown-based playbooks that extend what Claude Code can do. Instead of explaining the same workflow every session — how to deploy, how to write commit messages, how to review PRs — you write it once as a skill, and Claude follows it consistently. With over 77,000 GitHub stars and adoption across the developer community, Claude Code has become a central tool in many development workflows. In this post, we'll explore how skills work, how to create your own, and the patterns that make them effective.\n\n### What Is Claude Code?\n\nBefore diving into skills, let's establish what Claude Code brings to the table. It's an agentic coding assistant that operates directly in your terminal. Start it in any project directory:\n\n```bash\nclaude\n```\n\nFrom there, you interact through natural language. Ask it to refactor a function, fix a bug, explain a piece of code, or create a pull request. What makes it \"agentic\" is that it doesn't just suggest — it acts. A single request can trigger dozens of independent tool calls: reading files, searching code, editing multiple files, running tests, and committing changes.\n\nKey capabilities include:\n\n- **Full codebase understanding**: Claude reads and navigates your entire project, understanding relationships between files, modules, and dependencies.\n- **Multi-file editing**: Changes span as many files as needed. Rename a component and Claude updates every import.\n- **Terminal execution**: Runs build commands, tests, linters, and any shell command your workflow requires.\n- **Git integration**: Stages changes, writes commit messages following your conventions, creates branches, and opens pull requests.\n- **Multi-agent workflows**: Spawns parallel agents for large tasks, with a lead agent coordinating the work.\n- **IDE integration**: Available in VS Code, JetBrains IDEs, and as a standalone desktop app — in addition to the terminal.\n\nClaude Code also reads `CLAUDE.md` files at the start of every session. These project-level configuration files tell Claude about your architecture, coding standards, build commands, and conventions. Think of `CLAUDE.md` as the persistent context and skills as the on-demand playbooks.\n\n### Understanding Skills\n\nSkills are the mechanism for teaching Claude Code how to handle specific tasks. Each skill is a directory containing a `SKILL.md` file — a markdown document with frontmatter metadata and natural language instructions.\n\nThe key insight is how skills are loaded. At startup, Claude only reads the **name and description** of each available skill. The full instructions are loaded into context only when a skill is actually invoked. This progressive disclosure keeps context usage efficient — you can have dozens of skills installed without paying a context cost for all of them.\n\nSkills can be invoked two ways:\n\n1. **Directly** by typing `/skill-name` in the conversation\n2. **Automatically** by Claude when it determines a skill is relevant based on its description\n\nThis dual invocation model means skills can serve as both explicit commands and background knowledge that Claude draws on when appropriate.\n\n#### Where Skills Live\n\nSkills can be defined at three levels, each scoped differently:\n\n| Level | Path | Applies To |\n| --- | --- | --- |\n| Personal | `~/.claude/skills/