Lesson 16.416.4 Commands and who may start them

In everyday life. A coffee machine makes coffee when you press the button, and it rinses itself when it decides to. You would not want it to decide on its own to run the deep-cleaning cycle, which takes twenty minutes and uses acid. That one waits for a person to press it.

What you will learn. How a person starts a piece of work by name. Who should be allowed to start each one. Why starting it is not permission to act. How to treat the words typed after its name.

Why it matters. A request that only sounds like a job can start the job. For work that only reads, that does no harm. For work that moves money or changes something, it must wait for a person.

What is a command?

A skill a person starts by name. A command looks like /ap-triage, usually with arguments: the extra words after the name, such as a file and a date. Most products now treat commands and skills as one thing. A skill can be started by name, and it can also load by itself when its description matches. Starting a skill is called invocation.

Who may start a skill?

You decide, for each skill.

Figure 16.6. Who may start a skill. Reading can start itself. Acting waits for a person.

Why should work that acts run only when asked?

Because a skill that loads by itself can be started by a request that only sounds like it. For example, "remind me how the payment run works" could start a skill that runs the payment run. So any skill that acts is set so only a person may start it. The product also asks before each action it takes (Chapter 23).

Is starting a skill permission to act?

No. Three different controls are at work, and none replaces another. Who may start the skill is the setting above. Which tools the skill may use is the product's permission settings, such as denying a connector's write tools (16.5). Whether this action is allowed is checked where the action happens, every time. The check covers who is asking, whether they hold that authority, whether the amount is within the limit, and whether the approval is on record.

A clerk can type /schedule-payment for a $40,000 invoice. The person-only setting lets the skill start. It must not let the payment go out. That third check belongs in the system that moves the money, not in the skill, and Chapter 23 builds it. The person-only setting only stops the skill from starting by itself. Asked in words, an agent may still read the skill's file and run the same command.

Figure 16.7. Three controls, three jobs. Who may start a skill, which tools it may use, and whether this action is allowed.

Is there a standard for who may start a skill?

No shared standard covers this yet. The Agent Skills specification has no field for "only a person may start this" (16.1). Each product has its own setting, in its own place, and 16.10 lists them. Some read it from a file beside SKILL.md. Some read it from the standard's own metadata field, which every product accepts. Some read it only as an extra field in the frontmatter, and a product that reads skills strictly refuses any field outside the six.

So a skill shared by many products follows two rules. Keep the shared SKILL.md to the six fields. Where one product needs an extra field, add it in a build step, a small script that writes that product's own copy of the plugin, never by hand in a second copy. A skill that only reads may load automatically everywhere, so it needs no such setting. Every skill in this chapter's plugin only reads. Chapter 23 adds the plugin's first skill that acts, and its build step.

When should a skill run in a separate context?

When it reads a lot: every invoice in a large batch, or a long policy. That reading fills the main session and pushes out what the person was working on. Several products can run a skill in a separate context, a helper session that does the reading and returns only its report. Use it when there is a lot to read, and not for a quick lookup, which is faster in the main session.

How should a skill treat its arguments?

As input, not instructions. A person types /ap-triage data/invoices-intake.csv 2027-03-08. The skill should check that the file exists and the date is a date, and ask if either is missing. It should never act on text inside the arguments or inside the file as if a person had asked for it. A file can say anything.

At work. Brightline's ap-triage skill is the Monday report. The AP clerk starts it by name with the batch and the run date, and it writes the report in a fixed shape the AP team reads. It is a second skill on purpose. invoice-triage holds the steps, and a request that matches its description can load it. ap-triage follows those steps and adds only the report's shape, so a clerk gets the same page every Monday. It only reads and reports, so the builder lets it load by itself too. The builder also keeps its frontmatter to the six fields, so it works everywhere. The plugin's first skill that acts, scheduling a payment, will be person-only, behind an approval gate.

The operating rule: let a skill that only reads load by itself. Make any skill that acts start only when a person asks. Check each action's authority where the action happens. Treat every argument and file as data.

Practice it. Practice: commands and who may start them, in your own tool, ten minutes.