# Who invokes a skill, and where it lives

> Decide whether the agent may start a skill on its own or only a person may, what each choice costs in context, and whether the skill belongs in the project, in your own configuration or with the organization, including which one runs when two share a name.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/who-invokes-a-skill/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

The last lesson wrote a release skill and saved it in the package at
`.claude/skills/release/SKILL.md`. That file came with decisions the
lesson made by default. One is who may start the skill. As written, the
agent loads it when a request matches the description, and you can also
start it by typing `/release`. The other is where the file is. The file
is in the project's folder, so once it is committed the whole team has
it. Nobody outside the repository does.

This lesson makes both decisions on purpose. Who may start a skill is
its invocation mode, and where it is installed is its skill scope. You
don't run anything here. The examples are a few lines of front matter
and a few folder paths, and the exercise is a decision you write down.

## Who may start a skill

In Claude Code, a skill with no extra settings can be started two ways.
You type its name after a slash, or the model loads it when your request
matches its description. Each of these front matter fields removes one
of the two (Extend Claude with skills, Claude Code documentation):

- `disable-model-invocation: true` takes the model out. Only a person
  who types `/name` starts the skill. If the model tries to start it
  anyway, Claude Code refuses the call.
- `user-invocable: false` takes the person out. The skill is no longer
  in the `/` menu, and typing its name doesn't run it. The model still
  loads it when a request matches.

The choice also decides what the skill costs before anyone uses it. A
skill the model may start has its description in the context of every
session, so the model can match requests against it. A skill only a
person may start has no description in context, and nothing of it loads
until someone types its name (Extend Claude with skills, Claude Code documentation). A skill with no
side effects that helps only rarely, such as a report you run a few
times a year, still puts its description in every session in between
while the model may start it. Making it person-only removes that cost.

| Front matter | A person may start it | The model may start it | Description in every session |
| --- | --- | --- | --- |
| Neither field | Yes | Yes | Yes |
| `disable-model-invocation: true` | Yes | No | No |
| `user-invocable: false` | No | Yes | Yes |

Make a skill person-only when a run has effects you want to time
yourself. A deploy, a message to a channel other people read, and a
deletion on a shared account are examples. A model-invoked skill starts
whenever a request looks like its description, and a request can look
like it on a day nobody meant to deploy. Claude Code's own page gives
side effects as the reason for the field (Extend Claude with skills, Claude Code documentation). The
release skill from the last lesson commits and tags, but it doesn't push.
A wrong run stays on your machine, and `git` can undo it. Leaving it
model-invoked is a fair choice. A version that also pushes the tag would
be person-only.

Leave the model in when the skill holds knowledge or a procedure that
should apply whenever the work calls for it, such as the team's rules for
writing a database migration. The model-only setting,
`user-invocable: false`, is for a skill that a person wouldn't run as a
command, such as notes on how an old module works, which the agent needs
when it edits that module and a person never types.

A sentence in the description such as "use only when the user asks" is
text the model reads and weighs. It isn't a setting, so the description
is still in context, and the model can still decide that a request
matches. The field is what Claude Code enforces.

These two fields are Claude Code's own. The open skill format lists
`name`, `description`, `license`, `compatibility`, `metadata` and
`allowed-tools` as its front matter fields, and none of them says who may
start a skill (Agent Skills specification, agentskills.io). Claude Code's page also says that when
you upload a skill to claude.ai, a field outside that list makes the
upload fail (Extend Claude with skills, Claude Code documentation). When you move a skill to another
product, check how that product decides who starts it.

#### Checkpoint: Who should be able to start it?

Buckets:

- Only a person starts it
- The model may start it

Items:

- Deploy the main branch to production
- Apply the team rules for writing a new database migration
- Post a summary of the week to the team chat channel
- Explain how the old invoice export works when a task touches it

#### Pitfall: The announcement that sent itself

A team writes a skill that drafts the release notes and emails them to
the customer mailing list, and leaves the front matter at its defaults.
One month on, a developer asks the agent to "write up what changed this
week" for an internal meeting. The request matches the description, the
model loads the skill, and the draft goes to customers. The steps were
right, and the problem was the model's permission to start them. Give
every skill that sends, publishes, deploys or deletes
`disable-model-invocation: true` before you commit it.

## Where a skill is installed

The folder a skill is in decides who has it. Claude Code reads skills
from these places (Extend Claude with skills, Claude Code documentation):

| Scope | Folder | Who has it |
| --- | --- | --- |
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, in every project on this machine |
| Project | `.claude/skills/<name>/SKILL.md` in the repository | Everyone who works in the repository, once it is committed |
| Enterprise | `.claude/skills/<name>/SKILL.md` in the managed settings directory | Every user on the machines where the organization installs it |

A plugin can also carry skills. [The lesson on
plugins](https://schubergphilis.github.io/ai-training/customizing-agents/plugins/) covers those. Claude Code gives
each plugin skill the plugin's name as a prefix, so it never clashes with
a skill in these folders (Extend Claude with skills, Claude Code documentation).

A project skill is part of the repository. It changes in a commit, a
reviewer reads the change, and a colleague who pulls the branch gets the
same version you have. Put a skill there when the team needs it to work
on that code, such as the release procedure of the package. A personal
skill is only on your machine and changes when you edit it. It suits a
habit of your own that you want in every project, such as the format you
like for meeting notes.

When two of these folders hold a skill with the same name, Claude Code
runs one of them. Enterprise wins over personal, and personal wins over
project (Extend Claude with skills, Claude Code documentation). A personal `release` skill in your home
directory hides the team's `release` skill in the repository, and
`/release` runs your copy, even when it is months out of date.

#### Checkpoint: Where does each skill go?

Match each skill to the folder it belongs in.

Statements:

- The steps to rebuild this repository's test database, which every contributor needs
- The way you like to draft your own stand-up notes, in every project you work on
- A security review the company requires on every developer machine
- The team's release procedure for this package

Options:

- The project, committed to the repository
- Your own configuration in your home directory
- The organization's managed settings directory

#### Checkpoint: The release that skips a step

Last week the team added a changelog check to the project's release
skill. When a colleague types `/release`, the agent skips that check, and
on your machine it doesn't. What do you change?

- Restart the session, so that Claude Code reads the updated project skill again.
- Set `disable-model-invocation: true` on the project skill, so only a person can start it.
- Delete or rename the personal copy in the colleague's home directory.
- Add the new step to the project skill's description, so the model sees it first.

## Exercise

A team plans to add the skills below to one repository. For each one,
write down who may start it (only a person, or the model as well) and
where it goes (the project or your own home directory). Then write the
folder path and the front matter line you would add. Write "none" when
the defaults are right.

1. A skill that opens a pull request and asks the two code owners to
   review it.
2. Your own rules for wording commit messages, which you follow in every
   project and nobody else on the team uses.
3. A skill that explains what each error code in this service's logs
   means, for any task where the agent reads the logs.
4. A skill that deletes the team's preview environments that are older
   than a week, on the shared cloud account.

A good result: skills 1 and 4 are person-only, with
`disable-model-invocation: true`, because both act on things other people
see or use. Skills 2 and 3 leave the model in and don't need a line. Skill 3
could also be model-only with `user-invocable: false`, since nobody types
it as a command. Skills 1, 3 and 4 go in the project's
`.claude/skills/`, because the team needs them for this code, and skill
2 goes in `~/.claude/skills/`. Which skill did you hesitate on, and was
the doubt about who starts it or about who has it?

Stretch: List the skills in your own ~/.claude/skills/ folder and in the .claude/skills/ folder of a repository you work in. Is any name in both? If so, which one runs when you type it, and is that the one you want?

## Recap

1. In Claude Code, a person and the model can both start a skill unless
   the front matter says otherwise. `disable-model-invocation: true`
   leaves only the person, and `user-invocable: false` leaves only the
   model (Extend Claude with skills, Claude Code documentation).
2. Make a skill person-only when a run deploys, sends, publishes or
   deletes. A sentence in the description is advice to the model, and
   the field is a rule Claude Code enforces.
3. A skill the model may start has its description in every session. A
   person-only skill costs no context until someone types its name
   (Extend Claude with skills, Claude Code documentation). For a rarely used skill that saving can
   decide the choice, even when the skill has no side effects.
4. A project skill is committed to the repository and reaches the whole
   team, and a personal skill in your home directory reaches only you, in
   every project. When names clash, enterprise wins over personal and
   personal over project (Extend Claude with skills, Claude Code documentation).
5. The open skill format has no field for who starts a skill, so check
   how each product decides it when you move a skill (Agent Skills specification, agentskills.io).

#### Habit

Before you commit a skill that sends, publishes, deploys or deletes
anything, check that its front matter says only a person may start it.

## References

- Extend Claude with skills, Claude Code documentation, https://code.claude.com/docs/en/skills
- Agent Skills specification, agentskills.io, https://agentskills.io/specification