Skill System

Skills are reusable instruction sets that exist as SKILL.md files. During execution, an Agent can read skill content via tools and inject it into the conversation as additional context. Skills let you encapsulate domain knowledge, workflows, and best practices as standardized, reusable units.

What Is a Skill

A skill is fundamentally a file containing a YAML frontmatter and a Markdown body:

---
name: Code Review Standards
description: Unified code review standards and checklist for the project
---

# Code Review Standards

## Required Checks

1. Does the code follow naming conventions?
2. Are there any unused imports?
3. Does the file exceed the line limit?
4. Are there any leftover `console.log` statements?

## Review Template

**File**: `{filename}`
**Issues found**: {N}
**Severity**: High / Medium / Low

| # | Issue | Location | Suggestion |
|---|-------|----------|------------|
| 1 | ... | L42 | ... |

The Agent uses the list_skills tool to see available skills, then uses the read_skill tool to retrieve the content of a specific skill and reference it when executing a task.

Skill Discovery Locations

Skills are discovered and loaded in the following order:

Priority	Location	Path	Source Tag	Description
1	Workspace	.claude/skills/<name>/SKILL.md	workspace	Current project only
2	Project	<projectRoot>/.claude/skills/<name>/SKILL.md	project	Shared at project level
3	Personal	~/.claude/skills/<name>/SKILL.md	personal	Available globally for the user
4	Plugin	~/.elftia/plugins/skills/<name>/SKILL.md	plugin	Community-installed skills
5	Built-in	Bundled with the app	builtin	Elftia preinstalled skills

When skills share the same name, the one with the higher priority takes precedence.

Skill Tools

Agents interact with the skill system via two built-in tools:

list_skills

Lists all available skills and their descriptions.

Parameters: None

Example output:

Available skills:
- code-standards (workspace): Project coding standards and best practices
- architecture-index (workspace): Project architecture index and file location guide
- build-optimization (personal): Build optimization standards

read_skill

Reads the complete content of a specified skill.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Skill name

Returns: The full Markdown content of the skill file.

SkillHub Community Marketplace

SkillHub is a community marketplace for skills where you can search for and install skills shared by other users.

Searching for Skills

Agents can use the skillhub_search tool to search for community skills:

Search for skills related to "React best practices"

Installing Skills

Once you find a skill you want, use the skillhub_install tool to install it locally:

Install the skill "react-best-practices" to the personal directory

Installed skills are saved to ~/.elftia/plugins/skills/ and are available to all projects.

Associating Skills with an Agent

There are two ways to associate skills with an Agent:

Method 1: Declare in the Agent Configuration

Use the skills field in the Agent's frontmatter:

---
name: Code Assistant
skills:
  - code-standards
  - architecture-index
---

With this configuration, the Agent will automatically inject the content of these skills into the system prompt at startup.

Method 2: Read at Runtime

During execution, the Agent can actively call list_skills and read_skill to retrieve skill content:

User: Please review this code according to the project standards
Agent: Let me check the available skills first... [calls list_skills]
Agent: Found the code-standards skill, let me read it... [calls read_skill]
Agent: Based on the standards, I found the following issues...

Creating Custom Skills

Steps

1. Choose a storage location for the skill:

   • Project-specific → .claude/skills/<name>/SKILL.md
   • Globally available → ~/.claude/skills/<name>/SKILL.md

2. Create the directory and file:

mkdir -p .claude/skills/my-skill

3. Write the SKILL.md file:

---
name: My Skill
description: One-sentence description of the skill's purpose
---

# Skill Title

Detailed skill content...

SKILL.md Format Reference

Basic Format

---
name: Skill name
description: Brief description of the skill
---

Skill body content (Markdown format)

Full Format (with extended metadata)

---
name: Skill name
description: Skill description
always: false
allowedTools:
  - Read
  - Grep
  - Glob
metadata:
  always: false
  emoji: "📋"
  os:
    - win32
    - darwin
    - linux
  requires:
    bins:
      - node
      - npm
    env:
      - GITHUB_TOKEN
---

Skill body...

Frontmatter Field Reference

Field	Type	Description
name	string	Skill display name
description	string	Brief description
always	boolean	Whether to always inject into the system prompt (default: false)
allowedTools	string[]	Tool allowlist when using this skill
metadata.always	boolean	Same as always (nested format)
metadata.emoji	string	Display icon
metadata.os	string[]	Platform restriction (empty = all platforms)
metadata.requires.bins	string[]	Required CLI tools
metadata.requires.env	string[]	Required environment variables

Always-on Skills

Skills with always: true are automatically loaded into the system prompt every time an Agent starts, without needing to be declared in the Agent configuration. This is useful for project-level base standards.

Tool Allowlist

The allowedTools field can restrict the set of tools available to an Agent when using that skill. This is useful in security-sensitive scenarios, for example:

allowedTools:
  - Read
  - Grep
  - Glob

This restricts the Agent's available tools to read-only tools.

Skill Writing Best Practices

Clear Structure

---
name: API Design Standards
description: RESTful API design guide and naming conventions
---

# API Design Standards

## Naming Rules
- URLs use kebab-case
- Query parameters use camelCase

## Status Code Usage
- 200: Success
- 201: Created
- 400: Bad request parameters

## Checklist
- [ ] Does the URL conform to RESTful conventions?
- [ ] Is there appropriate error handling?
- [ ] Is pagination supported?

Practical Tips

1. Focus on a single topic — one skill addresses one category of problem
2. Provide concrete examples — include code snippets and templates
3. Use checklists — makes it easy for the Agent to execute systematically
4. State scope — describe prerequisites and limitations of the skill
5. Keep it concise — avoid overly long skill content that consumes too much of the context window

FAQ

Problem	Cause	Solution
Agent cannot find a skill	Skill file is not in the correct path or name does not match	Use list_skills to confirm available skill names
Skill content not injected into system prompt	Not declared in the Agent config and always is false	Add it to the skills field or set always: true
Tools required by the skill are unavailable	Agent tool allowlist does not include the required tools	Add the necessary tools to the Agent configuration
Platform restriction makes skill unavailable	metadata.os restricts the current platform	Modify the os field or install the required dependencies on the current platform
Skill content too long, hurting performance	Skill content consumes too much of the context window	Split into multiple smaller skills and load on demand
SkillHub search returns no results	Search keywords do not match	Try different keywords or search in English

Related Links

• Agent Overview — Agent system overview
• Creating Custom Agents — Configure skills in an Agent
• Tool Permissions & Security — Tool allowlist mechanism