Claude Code — Skills
- File format
- Markdown
- Discovery path
-
.claude/skills - Global install path
-
~/.claude/skills - Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
- Native frontmatter fields
-
name,description,license,compatibility,metadata,allowed-tools,disallowed-tools,context,agent,model,effort,disable-model-invocation,user-invocable,argument-hint,hooks
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
description | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | description | yaml frontmatter key: description (recommended, not required; if omitted uses first paragraph of markdown content) |
name | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | display_name | yaml frontmatter key: name (optional, falls back to directory name; lowercase letters, numbers, hyphens only, max 64 characters) |
user-invocable | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | user_invocable | yaml frontmatter key: user-invocable (optional bool, default true); controls /menu visibility only, not Skill tool access |
agent | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | The agent frontmatter field selects which subagent type executes the skill when context: fork is set (e.g., 'Explore', 'Plan'). |
allowed-tools | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Pre-approves tool calls while the skill is active; does not restrict tool availability. Accepts space-separated string or YAML list. For project skills, takes effect after workspace trust dialog is accepted. |
argument-hint | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Shows expected argument format during autocomplete (purely presentational). |
context | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Runs the skill in an isolated subagent with no conversation history when set to fork; companion agent field selects the subagent type (e.g., Explore, Plan). |
disable-model-invocation | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | disable_model_invocation | Claude auto-invokes skills whose description matches the conversation; opt out via disable-model-invocation: true. |
disableSkillShellExecution | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Disables inline shell command injection for user/project/plugin/added-directory skills; each command replaced with '[shell command execution disabled by policy]'. Bundled and managed skills are not affected. |
effort | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Overrides the session effort level (low/medium/high/xhigh/max) while the skill is active. |
hooks | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Attaches lifecycle hooks that fire only while this skill is active; supports once: true flag on individual handlers (honored only in skill frontmatter, not settings files). |
model | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Overrides the session model for the current turn while this skill is active; session model resumes on next prompt. Accepts same values as /model or 'inherit'. |
paths | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Limits auto-activation to file glob matches; accepts comma-separated string or YAML list; explicit /skill-name invocation remains unrestricted. |
shell | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Selects bash (default) or powershell for inline command execution blocks within the skill. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 for powershell. |
when_to_use | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to description in the skill listing and counts toward the 1,536-character cap. |
arguments | Preserved Conversion type: Preserved Syntax survives conversion but the target provider may not interpret it. Learn more → | — | Named positional arguments for $name substitution in skill content. Declared as a space-separated string or YAML list in the arguments frontmatter field; names map to argument positions in order. |
skillOverrides | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | The skillOverrides setting in settings.json controls skill visibility without editing SKILL.md. States: 'on' (name+description in context, in /menu), 'name-only' (name only in context, in /menu), 'user-invocable-only' (hidden from Claude, in /menu), 'off' (hidden from both). The /skills menu writes this setting interactively. Plugin skills are not affected. |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
canonical_filename | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Fixed filename SKILL.md required inside skill directory |
custom_filename | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Variable directory name: .claude/skills/<name>/SKILL.md — directory name is the skill identifier |
global_scope | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | ~/.claude/skills/<skill-name>/SKILL.md in user home directory |
project_scope | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | .claude/skills/<skill-name>/SKILL.md committed to version control |
shared_scope | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Managed settings deployment for organization-wide distribution |
| Agent Skills Open Standard Compliance | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | Claude Code skills follow the Agent Skills open standard (agentskills.io) with CC-specific extensions layered on top. |
| Skill Permission Rules | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | Skill, Skill(name), and Skill(name *) permission rules restrict which skills Claude may invoke programmatically. A few built-in commands (/init, /review, /security-review) are also available through the Skill tool. |
| Argument and Session Variable Substitution | Preserved Conversion type: Preserved Syntax survives conversion but the target provider may not interpret it. Learn more → | Skills support $ARGUMENTS (all args), $ARGUMENTS[N] (0-based index), $N (shorthand for $ARGUMENTS[N]), $name (named argument from arguments frontmatter), ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}, and ${CLAUDE_EFFORT} string substitutions. Named arguments declared as space-separated string or YAML list in arguments frontmatter map to positions in order. |
| Shell Command Injection for Dynamic Context | Preserved Conversion type: Preserved Syntax survives conversion but the target provider may not interpret it. Learn more → | Inline !`command` and ```! fenced blocks execute shell commands and inject output before Claude sees the prompt. |
| Additional Directory Skills Loading with Live Reload | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Skills in --add-dir directories are loaded with live change detection (other .claude/ configuration is not loaded from added directories). |
| Bundled Skills | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Claude Code ships built-in prompt-based skills (/simplify, /batch, /debug, /loop, /claude-api, /fewer-permission-prompts) immune to the shell-execution policy. |
| Live Change Detection for Skill Directories | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Adding, editing, or removing a skill file takes effect within the current session without restarting. Creating a top-level skills directory that did not exist at session start requires a restart. |
| Nested Directory Auto-Discovery | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Claude Code automatically discovers skills from .claude/skills/ directories along the path to edited files (monorepo support). |
| Plugin Scope | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Plugin-bundled skills use a plugin-name:skill-name namespace separate from enterprise/personal/project priority ordering. |
| Skill Content Lifecycle and Compaction Behavior | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Skill content enters context once per invocation and stays for the session. Auto-compaction re-attaches the most recent invocation of each skill (first 5,000 tokens each) within a 25,000-token combined budget, filling from most-recently-invoked first. |
| Skill Description Context Budget | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Skill descriptions share a dynamic budget (1% of context, 8,000 char fallback) with a 1,536-character per-entry cap (combined description + when_to_use text), raisable via SLASH_COMMAND_TOOL_CHAR_BUDGET. Individual skills can be set to name-only in skillOverrides to free budget. |
| Supporting Files | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Bundle templates, scripts, and reference docs alongside SKILL.md; loaded on demand via ${CLAUDE_SKILL_DIR}. |
Sources
| Source |
|---|
| https://code.claude.com/docs/en/skills.md |