Skills

A skill is a written procedure the agent can load when it's relevant - how to cut a release, how to add a migration, how this project wants a new endpoint wired up.

The agent always sees each skill's name and one-line purpose. It reads the full text only when a task calls for it, so a large library of skills doesn't crowd the context window.

Where they live

Skills come from three places. On a name collision the earlier one wins:


1. ~/.jan/projects/<slug>/skills/        project: this project only
   ├── release/
   │   └── SKILL.md                       # folder form, can bundle scripts alongside
   └── add-migration.md                   # flat form
2. ~/.jan/projects/<slug>/plugins/<P>/    plugin skills, always named <P>:<name>
3. ~/.jan/skills/                         user: every project on this machine
4. jan                                    built-in onboarding skill

Put a skill in ~/.jan/skills/ to use it from every project. A project skill with the same name shadows the user one in that project. Plugin skills never collide, because they're always qualified as <plugin>:<name>. A project or user skill named jan replaces the built-in one.

Run /skills in the console to see every skill with its scope. A skill hidden by a higher-precedence one is marked shadowed by project.

Skill folders can be symlinks in either scope, for example ~/.jan/skills/review -> ~/my-skills/review. Jan follows them. If the same folder is reached twice, it's listed once. Dangling links and symlink loops are skipped.

The folder form is what new and imported skills are written as, and it lets a skill ship helper scripts or templates next to its instructions. The format matches the wider SKILL.md ecosystem, so skills written elsewhere generally work here.

The model sees skills rebuilt from disk on every run. To refresh the / popup after adding, editing, or deleting one mid-session, including a user skill, run /reload skills. It reports what was added, removed, or changed.

Writing one

A skill is markdown with a name and a description:


---
name: release
description: Cut and publish a release
---
# Cutting a release
1. Confirm `main` is green in CI.
2. Bump the version in `Cargo.toml` and `package.json` - they must match.
3. Update `CHANGELOG.md`; group by feat/fix/chore.
4. Tag `v<version>` and push the tag. CI does the rest.
Never publish from a dirty working tree.

Keep it concise. A skill competes for the same attention as everything else in the prompt.

You can write the file yourself, or ask the agent to:


Write a skill for how we cut releases, based on what you see in CHANGELOG.md and the CI config

skill_write writes to the project by default. Ask for a user skill ("save this as a user skill") and the agent passes scope: "user", which writes to ~/.jan/skills/<name>/SKILL.md.

Who can invoke a skill

A skill has two invocation sides, and frontmatter closes either one:

User-invoked - you type /release (or /skill:release) in the console, or pick it from the slash popup.
Model-invoked - the agent sees the skill's description in its catalog and can fire it on its own by loading it with skill_read.

By default both sides are open. user-invocable: false hides a skill from you; disable-model-invocation: true hides it from the agent. See Skill Invocation for the full mechanics, the trade-offs, and when to use which.

Skills can also be installed as plugins - whole skill collections cloned from a git repo or picked from a marketplace, invocable under <plugin>:<skill> names.

Tools

Tool	Approval
`skill_list`	No
`skill_read`	No
`skill_write` (`scope`: `project` default, or `user`)	No, unless denied in `[tools]`

skill_list and skill_read cover every scope above, including plugin skills (skill_read accepts <plugin>:<name>, or the plain name when it's unique).

Controlling which are active


[skills]
enabled = []        # empty means all skills are enabled

enabled is a whitelist across every scope. It matches a plain name, a qualified <plugin>:<name>, or a plugin name, which enables all of that plugin's skills. Every enabled skill's name and purpose goes into the system prompt, and the body loads on demand.

Older scaffolds had an inject = "always" | "relevance" key. It was never read, and Jan removes it from your agent.toml the next time the agent starts.

Jan Desktop's Cowork surface (nightly channel only) keeps its own skill store under <data folder>/agent-workspace/skills. It layers the attached folder's project skills on top of that store. It doesn't read ~/.jan/skills yet.

Skills, AGENTS.md, and memory

Three places that shape behaviour, easily confused:

	Scope	Loaded
`AGENTS.md`	Rules for everything the agent does here	Always
Skills	A specific procedure	On demand, when relevant
Memory	Facts the agent learned	Recalled as needed

Rule of thumb: if it applies to every task, it belongs in AGENTS.md. If it applies to one kind of task, make it a skill.

Memory Skill Invocation