Skills

A Skill is a directory containing a SKILL.md. The directory name becomes a slash command. Skills give your team a reusable, versioned way to encode multi-step workflows: /deploy, /review-pr, /summarize-changes.

Anatomy

my-skill/
├── SKILL.md        (required - frontmatter + body)
├── reference.md    (optional - loaded only when SKILL.md links it)
└── scripts/
    └── helper.sh   (optional - executable bundled with the skill)

A minimal SKILL.md:

---
description: Summarize uncommitted changes and flag anything risky.
---

Look at the current diff and produce a 2-3 bullet summary + a risks list.

Current changes:
!`git diff HEAD`

Drop this file at ~/.isonforge/skills/summarize-changes/SKILL.md, then in any project:

/summarize-changes

The !git diff HEAD`` is dynamic context injection: IsonForge runs the command and replaces the placeholder with its output BEFORE the model sees the skill content.

Where Skills live

Location Path Scope
User ~/.isonforge/skills/<name>/SKILL.md All your projects
Project <cwd>/.isonforge/skills/<name>/SKILL.md This project only
Compat <cwd>/.claude/skills/<name>/SKILL.md Read as-is (Claude Code repos)
Compat <cwd>/.claude/commands/<name>.md Read as single-file Skill

Project beats user when names collide.

IsonForge walks up parent directories to the git root, so starting in a subdirectory still picks up Skills at the root.

Frontmatter

---
name: deploy                       # optional, defaults to dir name
description: Deploy to production  # recommended - tells the model when to use
allowed-tools: bash read_file      # space- or comma-separated tools
disable-model-invocation: true     # default false - hide from model's suggestions
user-invocable: true               # default true - hide from / menu if false
---
Field Effect
name Override the directory-derived name. Lowercase, hyphens, no spaces.
description Shown in /skills. Helps the model decide when to suggest invoking it.
allowed-tools Tools auto-approved while this Skill is active.
disable-model-invocation true hides the skill from the model's awareness. Only the user can invoke it via /name.
user-invocable false hides from the / menu - the model can still invoke it. Use for background knowledge.

Substitution

When you invoke /skill-name foo "bar baz" 42, IsonForge substitutes before sending to the model:

Placeholder Replacement
$ARGUMENTS Full arg string: foo "bar baz" 42
$0 First token: foo
$1 Second token: bar baz (shell-style quoting)
$2 Third token: 42
$ARGUMENTS[N] Same as $N
${ISONFORGE_SESSION_ID} Current session id
${ISONFORGE_SKILL_DIR} Absolute path to this skill's directory

Unused $0..$9 are replaced with empty string.

Dynamic context injection

Wrap a shell command in `!``...``` to run it before the model sees the skill:

Current branch:
!`git rev-parse --abbrev-ref HEAD`

Recent commits:
!`git log --oneline -10`

Failing tests:
!`pnpm test 2>&1 | tail -30`

Output replaces the placeholder. Commands run with a 10-second timeout. Failures produce [shell command failed: <reason>] in-line so the model can react.

Multi-arg example

---
name: migrate-component
description: Migrate a component from one framework to another.
---

Migrate the $0 component from $1 to $2.

Read the file:
!`cat src/components/$0`

Preserve existing behavior and tests. Output the new file content.

Invoke:

/migrate-component SearchBar React Vue

The model sees Migrate the SearchBar component from React to Vue. plus the file content.

Bundling scripts

Place executables in the skill directory and reference them with ${ISONFORGE_SKILL_DIR}:

---
name: validate-yaml
description: Validate every YAML file in the repo.
allowed-tools: bash
---

Run the validator:

!`python3 ${ISONFORGE_SKILL_DIR}/scripts/validate.py .`

This means the skill works regardless of where the user installed it (user vs project scope).

Compatibility with Claude Code

.claude/skills/<name>/SKILL.md and .claude/commands/<name>.md are loaded as-is. Existing repos that use Claude Code don't need to migrate - just install IsonForge and /your-skill works.

Frontmatter fields IsonForge ignores (Claude-Code-specific without IsonForge analogue):

These don't error; they're silently ignored.

Listing what's installed

/skills

Lists every Skill in scope with name + description + source. Hidden Skills (user-invocable: false) are excluded.

Best practices