Author a skill

A skill is a directory whose SKILL.md gives the agent a reusable procedure. Use one to keep a prompt, its scripts, and its reference files together in project or personal scope.

The skills guide owns discovery, pinning, the Store, and day-to-day use. This page defines the package format and the behavior of each authoring field.

What you can do

How it works

Terms

Package layout

.claude/skills/
  deploy-staging/
    SKILL.md
    scripts/
      deploy.sh
    references/
      checklist.md

SKILL.md is an optional YAML frontmatter block followed by Markdown instructions. name falls back to the directory name. description falls back to the first meaningful body line.

---
name: deploy-staging
description: Deploy the current revision to staging and verify it.
argument-hint: '[service]'
arguments: service
allowed-tools: Bash(deploy *) Read
---

Run `./scripts/deploy.sh $service`, then check @references/checklist.md.

Keep instructions operational: name inputs, commands, expected evidence, and stopping conditions. Relative script paths are interpreted by the agent or shell command you author; Localix does not automatically execute files merely because they sit beside SKILL.md.

Discovery and write scope

Localix writes and deletes only in ~/.claude/skills and the open project's .claude/skills, the folders Claude Code reads. A skill in .agents/skills or .claude/commands can be shadowed by saving a skill with the same name in .claude/skills.

The scanner accepts nested skill directories within the selected root. It ignores archive folders, caps traversal at six levels and 2,000 entries, and reads regular UTF-8 SKILL.md files up to 1 MiB.

Project symlinks must resolve inside the working directory; personal skill symlinks may point outside the home directory. Plugin skill links stay inside their declared skill root. Once a directory contains SKILL.md, the container scan treats it as one skill and does not descend into its assets for nested skills.

Invocation pipeline

An explicit slash invocation of a filesystem or plugin skill, or of a command, follows this order:

1. Resolve the skill and reject it when user-invocable: false.
2. Substitute arguments, ${CLAUDE_*} paths and ${user_config.*} options; a sensitive option is a placeholder.
3. Run the bounded ! shell commands, each checked against the agent's permission rules with the skill's allowed-tools. A command the rules would deny or ask about aborts the invocation. An argument reaches a command as a shell variable, so it is printed, never run, whatever quoting the author put around it.
4. Attach the files @path names after the text, each read only inside the working directory or the skill's directory, at most 32 KiB per file and 128 KiB in all. The @path stays in the text.
5. Run inline with tool overrides, or start a child session for context: fork.

A skill the agent loads with the Skill tool goes through the same steps, its commands checked against the run's rules, and a context: fork skill starts a subagent as Agent would. A pinned or keyword-triggered skill takes a separate path: its stored body enters the prompt without the slash preprocessing pipeline, including tool overrides, fork routing, or skill hooks.

The system prompt can suggest saving a repeatable workflow through the Skill tool. Saving is a model decision or an explicit user request, not a guaranteed post-run action.

Configuration

Frontmatter reference

Token lists accept a YAML list, an inline array, or comma- or space-separated text. Parenthesized tool patterns remain one token, so Bash(git *) is not split at its space.

When the model loads a skill that no plugin ships, its hooks register only if every command hook would pass the run's permission rules as a Bash call, the check its !cmd lines meet. Plan mode, an agent without Bash, or a command the rules would ask about registers none of them.

keywords uses comma-separated phrases or a YAML list; spaces within a phrase are preserved. Keyword injection has its own 32,000-code-unit body budget and skips already pinned names. It adds instructions to the prompt; it does not guarantee that the model follows them or record curator use.

${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR} and, in a plugin skill, ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} inside an allowed-tools or disallowed-tools value resolve before the rule is created, so a skill can pre-approve its own bundled script.

Optional package policy

An adjacent agents/openai.yaml can disable implicit selection without changing SKILL.md:

policy:
  allow_implicit_invocation: false

This setting hides the skill from the model roster. Explicit slash invocation and pinning remain available. Missing, malformed, oversized, non-UTF-8, or escaping policy files are ignored.

Argument and session substitutions

An unknown named placeholder stays unchanged. When a body contains no argument placeholder, Localix appends a short Arguments: section for a non-empty argument string.

Dynamic command context

Use an inline or fenced ! form to insert stdout before the agent sees a filesystem skill:

Changed files: !`git diff --name-only HEAD~1`

```!
git status --short
git log --oneline -5
```

Commands run in the session working directory with stderr merged into stdout. Localix injects the CLAUDE_* values listed above (and, in a plugin skill, CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA), runs at most 16 commands with concurrency four, and allows two minutes and 32 KiB per command. Aggregate inserted stdout is capped at 64 KiB. A command that fails — a non-zero exit, except exit 1 from a search or comparison command, or a timeout — aborts the invocation, and the agent never sees the skill.

Before any command runs, each one meets the agent's permission rules as a shell call, typed or loaded by the agent: a denied command aborts the invocation, and so does one the rules would ask about, unless the skill's allowed-tools pre-approve it.

Shell expansion is single-pass: what a command prints, and a file @path inlines, reach the agent as plain text — a printed @path, ! command or $ARGUMENTS is not expanded again.

With "disableSkillShellExecution": true in a Claude Code settings file (managed settings, where nobody can turn it off, are the usual place), no command runs: each inline ! command and each fenced ! block of a skill or custom command from your folders, a project or a plugin is replaced by [shell command execution disabled by policy], the permission rules are not asked, and the rest of the skill renders as usual.

File references

An @path at line start or after whitespace, outside code spans and fences, can inline a text file:

Follow @references/release-checklist.md and report each failed item.

Resolution tries the session working directory and the skill directory. Real-path checks keep the target inside one of those roots. Each file is capped at 32 KiB; a run accepts at most 32 expansions, 128 candidates, and 128 KiB total. An unresolved reference stays literal.

Validate and test

Use the skill's page in the Store or the Skill tool to confirm discovery, then invoke the skill with representative arguments. Test both a successful path and the failure condition described by the procedure.

For dynamic context, keep commands read-only where possible and test their timeout, empty-output, and non-zero-exit behavior. For a forked skill, verify the invoking agent has every tool it needs.

Limits

• Filesystem skill bodies and adjacent assets live on disk. Session pin names are stored in the session database, so the skill system is not entirely filesystem-only.
• Personal and project skills are merged, personal first, as in Claude Code.
• Discovery reads Claude Code's .claude/skills and .claude/commands beside Localix's own, but no other application's folders. Skills below the working directory reach the agent once the session works with a file in that folder.
• shell and metadata are accepted without runtime behavior. version and license are retained as information only.
• Tool overrides apply to the turn that invokes the skill. A fork runs with its agent type's tools; a pin only injects instructions.
• Dynamic commands execute local code during slash preprocessing. They are not sandboxed beyond process, time, output, and count limits.
• Plugin skills are read-only through the Skill tool. Disable the owning plugin or copy the skill to a writable filesystem scope before editing it.
• Pinned skill bodies share a 32,000-code-unit prompt budget. Content after the aggregate cap is truncated and replaced with an omission notice.

Related guides

• Use and manage skills
• Install Claude Code plugins
• Hooks and commands
• The learning loop

Source of truth

• A scope's skills, read through the plugin kit
• The SKILL.md format as the kit reads it
• Writing skills to a scope's folder
• Slash-command dispatch
• Typed skill and command expansion
• The agent's rules for injected commands
• File-reference attachment
• Model roster and pinned-skill prompt sections