Skills

Skills are reusable bundles that combine prompt instructions with a set of required tools. They let you give the AI specific expertise and capabilities for particular tasks — without repeating yourself in every conversation.

What is a Skill?

A skill is a Markdown file (SKILL.md) that defines:

• Instructions — A prompt that tells the AI how to behave for this skill
• Required tools — Which built-in or MCP tools the AI should use
• Context — Any additional information the AI needs

When you apply a skill to a conversation, the instructions are injected into the system prompt and the required tools are automatically enabled.

Installing Skills from a URL

Found a skill online? Just paste the GitHub, GitLab, or Bitbucket URL into the chat. ChatShell’s built-in skill-installer will automatically download and install the skill into ~/.chatshell/skills/.

Supported URL formats:

• Repository root — github.com/user/repo (scans for all skills in the repo)
• Directory — github.com/user/repo/tree/main/skills/my-skill (installs that skill)
• SKILL.md file — github.com/user/repo/blob/main/skills/my-skill/SKILL.md (installs the parent skill directory)

If the repository contains multiple skills, ChatShell will list them and let you choose which ones to install.

Creating a Custom Skill

Each skill lives in its own subdirectory under the skills folder. Create a directory for your skill and add a SKILL.md file inside it:

~/.chatshell/skills/
└── my-custom-skill/
    └── SKILL.md

The SKILL.md file format:

---
name: My Custom Skill
description: What this skill does
tools:
  - web_search
  - web_fetch
  - bash
---

# My Custom Skill

You are a specialized assistant for [describe the task].

When the user asks you to [do something], you should:

1. First, [step one]
2. Then, [step two]
3. Finally, [step three]

Always [important constraint].
Never [important restriction].

Skill Frontmatter

Field	Required	Description
name	Yes	Display name for the skill
description	No	Short description shown in the skill picker
tools	No	List of tools to enable when this skill is active

Applying Skills to a Conversation

1. Open a conversation
2. Click the Skills button in the input toolbar
3. Select one or more skills to apply
4. The AI will now follow the skill’s instructions for this conversation

Skills can be combined — for example, applying both a “Web Researcher” skill and a “File Analyzer” skill in the same conversation.

Auto-Discovery

ChatShell’s skill scanner automatically discovers skills by looking for SKILL.md files inside subdirectories of configured skill directories. Each subdirectory is treated as one skill — the directory name is used as the skill identifier, and the SKILL.md inside it defines the skill’s behavior.

The default skills directory is ~/.chatshell/skills/. You can configure multiple skill source directories in Settings → Skills to organize skills from different sources.