augmnt.sh
Back to Blog

Mastering Claude Code Skills

9 min read
Claude CodeSkillsWorkflowProductivity

Skills in Claude Code are a powerful way to extend the AI's capabilities with reusable instructions and specialized knowledge. While sub-agents handle complex, multi-step tasks in separate contexts, skills provide inline guidance that shapes how Claude Code approaches specific types of work within your current conversation.

Understanding Claude Code Skills

Skills are defined in SKILL.md files that contain instructions, patterns, and best practices for specific domains or tasks. They work by injecting relevant context into Claude Code's understanding when triggered.

What Skills Are

At their core, skills are Markdown files with YAML frontmatter that define:

  • Name and description: How Claude Code identifies and understands the skill
  • Invocation rules: When and how the skill should be activated
  • Tool access: What capabilities the skill enables
  • Instructions: The actual guidance and patterns to follow

How Skills Work

Skills can be activated in several ways:

  1. Automatic invocation: Claude Code detects when a skill is relevant based on your request
  2. Manual invocation: Use /skill-name to explicitly activate a skill
  3. Proactive use: Some skills are designed to trigger automatically for certain file types or patterns

Where Skills Live

Skills can be stored in two locations:

  • Personal skills: ~/.claude/skills/ - Available across all your projects
  • Project skills: .claude/skills/ - Scoped to a specific codebase

This hierarchy allows you to maintain global preferences while tailoring behavior for individual projects.

Types of Skills

Skills generally fall into two categories based on their content:

Reference Content Skills

These skills provide domain knowledge, best practices, and patterns that Claude Code should follow. They're essentially expertise encoded as instructions:

---
name: react-patterns
description: Modern React patterns and best practices
---

When writing React components:
- Prefer functional components with hooks
- Use TypeScript for type safety
- Implement proper error boundaries
- Follow accessibility guidelines (WCAG 2.1)

Task Content Skills

These skills define specific workflows or procedures for accomplishing tasks:

---
name: commit
description: Create well-formatted git commits
user-invocable: true
---

When creating commits:
1. Stage only related changes
2. Write clear, conventional commit messages
3. Reference issues where applicable

Building Your First Skill

Let's create a simple skill for code organization. Create a file at .claude/skills/organizing-code/SKILL.md:

---
name: organizing-code
description: File organization patterns for React projects
---

## File Organization Principles

When organizing React project files:

### Component Structure
- Place components in `src/components/`
- Co-locate component tests: `Component.test.tsx`
- Co-locate styles: `Component.module.css`

### Utilities
- Place shared utilities in `src/lib/`
- Keep utilities focused and well-documented

### Hooks
- Custom hooks go in `src/hooks/`
- Name hooks with `use` prefix

This skill will automatically influence how Claude Code organizes code when working in your React projects.

The webdev-skills Collection

I've built a comprehensive collection of web development skills in the webdev-skills repository. These skills are designed for modern development workflows and cover essential areas:

CLI Tools

Skills for effectively using command-line tools in development:

  • Preferring CLI tools over web dashboards for reproducibility
  • Proper usage of git, npm, docker, and cloud CLIs
  • Scriptable and automatable commands

File Organization

Patterns for structuring React and Next.js projects:

  • Component colocation strategies
  • Shared utility organization
  • Feature-based vs. layer-based structures

Commits

Writing clear, meaningful commit messages:

  • Conventional Commits format
  • Semantic versioning alignment
  • PR description generation

Code Review

Structured approaches to reviewing code:

  • Prioritized feedback (critical → suggestions)
  • Security-focused review patterns
  • Performance considerations

Testing

Practical testing strategies:

  • Unit, integration, and e2e test organization
  • Test naming conventions
  • Coverage targets and when to test

Advanced Patterns

Dynamic Context Injection

Skills can pull in dynamic context using the ! command syntax:

---
name: project-aware
description: Context-aware project assistance
---

Current project structure:
!`find src -type f -name "*.ts" | head -20`

Use this structure to inform your recommendations.

Running Skills in Subagents

For skills that require isolated context, use the context: fork setting:

---
name: security-audit
context: fork
tools: [Read, Grep, Bash]
---

This runs the skill in a separate context window, preserving your main conversation.

Controlling Invocation

Fine-tune when and how skills are activated:

---
name: deploy
user-invocable: true
disable-model-invocation: true
---
  • user-invocable: true: Enables /deploy command
  • disable-model-invocation: true: Prevents automatic activation

Best Practices

Keep SKILL.md Focused

Each skill file should be under 500 lines. If you need more content:

  • Split into multiple related skills
  • Use supporting files that the skill references
  • Link to external documentation

Use Supporting Files

For extensive reference material, create additional files alongside SKILL.md:

.claude/skills/react-patterns/
├── SKILL.md           # Main skill definition
├── components.md      # Component patterns
├── hooks.md           # Hook patterns
└── testing.md         # Testing patterns

The skill can then reference these files as needed.

Configure Appropriate Tool Access

Only grant skills the tools they actually need:

---
name: read-only-review
tools: [Read, Grep, Glob]
---

This follows the principle of least privilege and prevents unintended side effects.

Version Control Your Skills

Keep project-specific skills in version control:

.claude/
├── skills/
│   ├── commit/
│   │   └── SKILL.md
│   ├── review/
│   │   └── SKILL.md
│   └── organize/
│       └── SKILL.md
└── settings.json

This ensures consistency across your team and allows skills to evolve with your codebase.

Getting Started with webdev-skills

Installation

  1. Clone the repository:
git clone https://github.com/augmnt/webdev-skills.git
  1. Copy skills to your Claude Code directory:
# For global access (all projects)
cp -r webdev-skills/skills/* ~/.claude/skills/

# For project-specific use
cp -r webdev-skills/skills/* ./.claude/skills/
  1. Start using skills:
# Automatic activation based on context
"Please organize these components following best practices"
# -> Activates organizing-project-files skill

# Manual invocation
"/commit"
# -> Activates writing-commits skill for commit message generation

Usage Examples

Code Review:

"Review this PR for security and performance issues"
# -> Activates reviewing-code skill with structured feedback

Writing Tests:

"Write tests for this authentication module"
# -> Activates writing-tests skill with appropriate patterns

Commit Messages:

/commit
# -> Generates conventional commit message based on changes

Skills vs. Sub-Agents

While both extend Claude Code's capabilities, they serve different purposes:

| Aspect | Skills | Sub-Agents | |--------|--------|------------| | Context | Inline, same conversation | Separate context window | | Complexity | Reference and guidance | Multi-step autonomous tasks | | Invocation | Automatic or /command | Delegated by Claude Code | | State | Stateless | Can maintain task state |

Use skills for injecting expertise and patterns. Use sub-agents for complex, multi-step workflows that benefit from isolated context.

Conclusion

Skills in Claude Code provide a lightweight but powerful way to extend AI capabilities with domain-specific knowledge and workflows. By encoding your team's best practices, patterns, and preferences into reusable skills, you create a more effective development experience that improves over time.

The webdev-skills collection offers a solid foundation for modern web development workflows. Start with these battle-tested skills, customize them for your needs, and build your own collection of expertise that makes Claude Code an even more effective development partner.

Whether you're standardizing commit messages, structuring code reviews, or organizing project files, skills transform Claude Code from a general-purpose assistant into a specialized collaborator that understands your workflow.