Skills

Skills are reusable, named instructions that show up as slash commands in Magic Coder. If you (or your team) define a skill called git-commit, typing /git in the input box will surface /git-commit as a suggestion. Selecting it inserts the command and the agent runs the skill’s prompt.

Skills are how you turn “the workflow we always run” into a one-keystroke command — drafting a commit message that follows the project’s conventions, generating a PR description, applying a code-review checklist, regenerating an artifact.

Where skills come from

Magic Coder loads skills from three places and merges them:

Source	Location	Loaded…
Workspace skills	<workspace>/.magic/skills/<name>/SKILL.md	…when the workspace is trusted.
User skills	~/.magic/skills/<name>/SKILL.md	…always, on every session.
Cloud (BridgeApp) skills	configured in BridgeApp	…always, on every session, while signed in.

If two sources define a skill with the same name, workspace wins over user, and local wins over cloud — so you can override a shared skill by defining a workspace-local version.

Authoring a skill

A skill is a Markdown file at .magic/skills/<skill-name>/SKILL.md. The directory name becomes the skill’s slash command (/<skill-name>) unless the file overrides it via frontmatter.

A minimal skill:

---
name: git-commit
description: Draft a commit message that follows the project's conventions.
---

You are about to draft a Git commit message for the staged changes.
Follow these rules:

- Use Conventional Commits: `<type>(<scope>): <summary>`
- Keep the subject under 70 characters
- Don't include emoji
- If the change touches more than one logical area, split into multiple commits

Now look at the staged changes and propose the commit message.

The body is the prompt the agent runs when the skill is invoked. Anything you can put in a prompt works — instructions, examples, a checklist, references to files in the repo.

Frontmatter

Key	Required?	Notes
name	optional	The skill’s display name and slash command. If omitted, falls back to the first # Heading in the body, then to the directory name.
description	optional	One-line description shown next to the slash command in the picker. If omitted, falls back to the first non-heading line of the body, then to “Local skill”.

File layout

<workspace>/.magic/skills/
├── git-commit/
│   └── SKILL.md
├── pr-description/
│   ├── SKILL.md
│   └── examples.md      ← extra files are fine; only SKILL.md is the entry point
└── repo-tour/
    └── SKILL.md

Or at the user level:

~/.magic/skills/
├── changelog-entry/
│   └── SKILL.md
└── style-fix/
    └── SKILL.md

The agent only reads SKILL.md files; other files in the skill directory are ignored by the discovery walk but can be referenced from the prompt body if you want.

Invoking a skill

Type / followed by some characters of the skill name. Magic Coder fuzzy-matches:

/gcm    → /git-commit
/rev    → /review

Press Tab or Enter to accept the suggestion. Press Enter again to send.

Some skills accept arguments after the slash command:

/git-commit fix the failing migration

The skill’s prompt receives the rest of the line as input.

Inline invocation

Skills can also be invoked mid-message:

We need to ship this branch. Use /git-commit to draft a commit message,
then /pr-description to draft the PR body.

When you type / mid-line, Magic Coder offers skill suggestions for that token (built-in slash commands aren’t suggested mid-line — only at the start). Accept a suggestion to expand the token, and continue typing.

Skills vs. built-in commands

Built-in commands — /login, /model, /clear, etc. — are part of Magic Coder itself and act on the TUI directly (they don’t go through the model). Skills are model-level: they expand into a prompt that the agent runs as part of the conversation.

Practically:

• Built-ins change client state (theme, model, sign-in). They never produce assistant output.
• Skills trigger an agent turn. They produce reasoning, tool calls, and assistant output, like any other message.

The slash menu mixes both — built-ins appear with a description; skills appear as /name — description.

Trust matters

Workspace skills are loaded only when the workspace is trusted. Until then, the agent doesn’t see your <workspace>/.magic/skills/ files. User skills (~/.magic/skills/) are loaded regardless of any individual workspace’s trust state — you’ve already decided to trust your own user-level files by putting them there.

See Workspaces & trust.

When to put a skill where

• Workspace — when the skill is repo-specific. The commit message convention, the test runner invocation, the deploy ritual. Commit .magic/skills/ to source control so your team shares it.
• User — when the skill is yours, personal, and works across repos. Your favorite /explain-this-file prompt, a /draft-meeting-notes skill you use on every project.
• Cloud (BridgeApp) — when the skill should follow you across machines and you want it managed alongside the rest of your BridgeApp account. Authoring cloud skills is currently done in BridgeApp directly.

Sharing skills

The simplest way to share a workspace skill with your team is to commit .magic/skills/ to the repo. Magic Coder reads from the same on-disk path on every developer’s machine — no install step needed.

Sharing user-level skills across machines is currently a copy-the-files exercise. Watch Skills authoring for richer authoring/distribution coming through BridgeApp.

When skills aren’t the right tool

• One-off questions. Don’t make a skill for something you’ll ask once — just ask it.
• Anything that needs hard control flow. Skills are prompts, not programs. Logic that needs branches, retries, or complex state belongs in something more structured. (See Programmatic usage — coming soon.)