What Are the Different Roles a Skill Can Have in Claude-Skills?

Claude-skills defines exactly four roles in every SKILL.md file—expert, specialist, architect, and engineer—each indicating a specific level of expertise or focus for that skill.

The Jeffallan/claude-skills repository organizes capabilities through modular skill definitions, where each skill's SKILL.md file declares its intended expertise level via a dedicated role field. Understanding these distinct roles is essential for correctly categorizing and invoking the appropriate skill during AI-assisted development workflows.

The Four Skill Roles in Claude-Skills

Every skill descriptor in the repository includes a metadata.role field that must be set to one of four specific values. These roles determine how the skill is positioned within the broader ecosystem and what level of domain knowledge it represents.

Expert

The expert role designates a senior-level specialist with deep domain knowledge. Skills carrying this role are intended for complex, nuanced tasks requiring extensive experience in a particular field. In skills/wordpress-pro/SKILL.md, the role is defined as expert to indicate deep WordPress development capabilities.

---
name: wordpress-pro
description: Use when deep WordPress development expertise is required
metadata:
  role: expert          # ← expert role

  ...

Specialist

The specialist role represents a proficient practitioner typically focused on a specific technology or task. While highly capable, this role indicates a narrower scope compared to the expert designation. The skills/vue-expert/SKILL.md file uses the specialist role to denote focused Vue.js proficiency.

---
name: vue-expert
description: Use when Vue.js expertise is required
metadata:
  role: specialist      # ← specialist role

  ...

Architect

The architect role is oriented toward high-level system design and architecture decisions. Skills with this role focus on structural planning, technology selection, and overarching design patterns rather than implementation details. The skills/rag-architect/SKILL.md demonstrates this with the architect role for RAG system design.

---
name: rag-architect
description: Use when designing Retrieval‑Augmented Generation systems
metadata:
  role: architect       # ← architect role

  ...

Engineer

The engineer role emphasizes practical engineering and operations work, such as DevOps, infrastructure automation, and deployment pipelines. This role bridges development and operations concerns. In skills/devops-engineer/SKILL.md, the engineer role identifies skills focused on pipeline and infrastructure automation.

---
name: devops-engineer
description: Use when DevOps pipelines and infrastructure automation are needed
metadata:
  role: engineer        # ← engineer role

  ...

How to Define a Role in Your SKILL.md File

To assign a role to your skill, include the role key within the metadata section of your SKILL.md frontmatter. The value must be exactly one of the four supported strings: expert, specialist, architect, or engineer.

---
name: your-skill-name
description: Describe when to use this skill
metadata:
  role: specialist  # Must be: expert, specialist, architect, or engineer

  version: 1.0.0
---

Ensure there are no typos or variations in capitalization, as the role field is used by the claude-skills system to categorize and select appropriate capabilities during task routing.

Summary

The claude-skills repository organizes capabilities through four distinct expertise levels defined in each SKILL.md file:

• Expert – Senior-level specialists with deep domain knowledge (e.g., skills/wordpress-pro/SKILL.md)
• Specialist – Proficient practitioners focused on specific technologies (e.g., skills/vue-expert/SKILL.md)
• Architect – High-level system designers focused on structural decisions (e.g., skills/rag-architect/SKILL.md)
• Engineer – Operations-focused practitioners handling DevOps and infrastructure (e.g., skills/devops-engineer/SKILL.md)

Frequently Asked Questions

What are the four skill roles in claude-skills?

The four skill roles are expert, specialist, architect, and engineer. These values are defined in the metadata.role field of every SKILL.md file across the repository to indicate the level of expertise or focus area for that particular skill.

How do I choose between expert and specialist roles?

Select expert when your skill represents senior-level, deep domain knowledge suitable for complex architectural decisions and nuanced problem-solving. Choose specialist when the skill focuses on proficient execution within a specific technology stack or task domain without requiring the broad strategic oversight of a senior expert.

Can I assign multiple roles to a single skill?

No, each SKILL.md file supports only one role value in the metadata.role field. The claude-skills system expects a single expertise classification to properly categorize and invoke the skill during task routing, so you must select the single most appropriate role for your skill's primary function.

Where are role examples documented in the source code?

Concrete implementations of each role are found in the repository's skills/ directory, specifically in skills/wordpress-pro/SKILL.md (expert), skills/vue-expert/SKILL.md (specialist), skills/rag-architect/SKILL.md (architect), and skills/devops-engineer/SKILL.md (engineer).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}