Skills System——Teaching AI Your "Secret Techniques"

Do you repeatedly tell AI “please write commit messages in this format”? Or “remember to use our code standards”?

Reminding every time is tedious. The Skills system solves this—teach AI your “secret techniques” and use them next time directly.

Today we’re talking about this “AI skill book.”

The diagram: Skills system is like a game skill book—after learning, you can use it

What Are Skills

Skills are encapsulated prompt templates that can be called by AI to execute specific tasks.

Simple understanding:

• Regular prompt: every time you have to say “please write Y in X format”
• Skill: define once, use many times, “use the writeCommitMessage skill”

Core value of skills:

• Reuse: Define once, use everywhere
• Standardization: Uniform behavior and output
• Simplification: Complex tasks become simple calls
• Shareability: Team sharing, community exchange

Built-in vs User-Defined Skills

Claude Code’s skills are divided into two categories:

Built-in Skills: Anthropic officially provided, ready to use out of the box.

- /commit: Generate standardized commit messages
- /pr: Generate PR descriptions
- /review: Code review checklist
- /test: Generate test cases

User-Defined Skills: Defined by users or teams themselves.

- Company code standards check
- Project-specific refactoring patterns
- Team documentation templates

The diagram: Built-in vs user-defined skills

Defining Skills

A skill is a YAML file that defines:

name: writeCommitMessage
description: |
  Generate standardized commit messages based on code changes.
  Use Conventional Commits format.
input:
  type: object
  properties:
    changes:
      type: string
      description: Description of code changes
run: |
  Please generate commit messages conforming to Conventional Commits specification based on the following code changes:

  {{changes}}

  Format requirements:
  - type(scope): subject
  - body (optional)
  - footer (optional)

  Example:
  feat(auth): add OAuth2 login support

  - Add Google OAuth provider
  - Update login UI
  - Add token refresh logic

  Closes #123

Key fields:

• name: Skill name, used when calling
• description: Skill description, used by model to decide whether to use
• input: Parameters the skill needs
• run: Prompt template for executing the skill

SkillTool: The Skill Executor

Skills are called through SkillTool:

// Model call
{
  tool: 'SkillTool',
  input: {
    skill: 'writeCommitMessage',
    changes: 'Added user authentication with bcrypt...'
  }
}

SkillTool workflow:

Receive Call → Find Skill Definition → Fill Template → Execute Prompt → Return Result

Template filling uses Jinja2 syntax:

run: |
  Please generate commit messages for the following code changes:
  {{changes}}

  Author: {{author}}
  Date: {{date}}

Input {changes: "...", author: "John", date: "2026-06-20"} gets filled as:

Please generate commit messages for the following code changes:
...

Author: John
Date: 2026-06-20

Skills vs MCP Tools

Both skills and MCP tools extend AI capabilities, but serve different purposes:

Simply put:

• Skills: Let AI “be better at tasks” (prompt-level extension)
• MCP Tools: Let AI “do more things” (capability-level extension)

The diagram: Differences and cooperation between skills and MCP tools

The two can work together:

• Skills call MCP tools to get data
• MCP tool results are processed by skills
• Skills decide when to use which MCP tool

Practical: Custom Skills

Let’s look at several practical skill cases.

Case 1: Code Style Check

name: checkCodeStyle
description: |
  Check code against team code standards.
  Return places that don't conform and suggestions.
input:
  code:
    type: string
    description: Code to check
  language:
    type: string
    description: Programming language
run: |
  Please check if the following {{language}} code conforms to our team standards:

  ```{{language}}
  {{code}}

Our standards:

• Function names use camelCase
• No semicolons at line ends
• Use 2-space indentation
• Comments use JSDoc format

Please list all places that don’t conform and provide modification suggestions.

**Case 2: Generate API Documentation**

```yaml
name: generateApiDoc
description: |
  Generate API documentation from code.
  Use OpenAPI format.
input:
  code:
    type: string
    description: API handler function code
run: |
  Please generate documentation in OpenAPI specification based on the following code:

{{code}}

Output format:
- Path
- Method
- Request parameters (including type, required, description)
- Response format
- Error codes

Case 3: Multi-language Translation

name: translateDoc
description: |
  Translate documentation to target language.
  Maintain technical term accuracy.
input:
  content:
    type: string
  targetLanguage:
    type: string
run: |
  Please translate the following content to {{targetLanguage}}, maintaining technical term accuracy:

  {{content}}

  Notes:
  - Keep code blocks as-is without translating
  - Keep proper nouns in English
  - Maintain Markdown format

Skill Management and Sharing

Where are skill files placed?

Project-level Skills: .claude/skills/*.yaml Only available for current project

User-level Skills: ~/.claude/skills/*.yaml Available for all projects

Built-in Skills: Embedded in Claude Code Available to everyone

Sharing skills:

# Export skill
claude skill export checkCodeStyle > check-code-style.yaml

# Import skill
claude skill import check-code-style.yaml

# Share with others
# Send YAML file directly, or publish to GitHub

Best Practices

Skill Design:

• Single responsibility: one skill does one thing
• Clear description: description accurately specifies use cases
• Reasonable parameters: not too many parameters, necessary ones have defaults
• Rich examples: include example outputs in run

Skill Naming:

• Use camelCase
• Start with verbs: write, check, generate
• Self-explanatory: know what it does without reading description

Skill Documentation:

• Explain use cases
• Provide example input/output
• Explain differences from related skills

Skill Versioning:

• Add version field in YAML file
• Update version for major changes
• Consider backward compatibility

Implications for Using Claude Code

Understanding the skills system helps you:

Reduce Repeated Prompts: Encapsulate commonly used prompts into skills

Standardize Team Workflow: Share skills, unify AI usage patterns

Improve AI Output Quality: Carefully designed skills are more reliable than ad-hoc prompts

Extend AI Capabilities: Extend without coding, using YAML

Summary

The skills system transforms AI from “general assistant” to “professional consultant”:

• Skills are encapsulated prompt templates
• SkillTool executes skills, fills templates, returns results
• Skills and MCP tools complement each other: skills extend “intelligence,” MCP extends “capability”
• Custom skills teach AI your “secret techniques”

This is the complete Claude Code skills system. Hopefully this series helped you deeply understand Claude Code’s underlying principles.

This series ends here. 12 articles, from architecture to prompt engineering, from context management to security permissions, from CLAUDE.md to skills system, taking you through a complete dissection of Claude Code’s internals.

If you found this valuable, feel free to like and share. Want to see more in-depth technical articles? Follow Monster Programming.