nessar
bb8d09dda4
- Created SKILL.md and SKILL-MECHANICS.md for writing agent skills. - Added openai.yaml for agent interface configuration. - Introduced AGENTS.md for agent skills overview. - Established CONTEXT.md for personal leave planning terminology. - Documented ordered heuristic optimization in ADRs. - Defined personal client-side planner limitations in ADRs. - Created domain documentation for engineering skills. - Added issue tracker guidelines for GitLab. - Mapped triage labels for issue tracking. - Initialized skills-lock.json to manage skill dependencies.
2.6 KiB
Skill mechanics
The skill-specific branch of writing-for-agents: what changes when the document is a skill — frontmatter, the invocation choice, and router skills. Everything else about writing it is the universal reference in SKILL.md.
Invocation
Two choices, trading the two loads:
- A model-invoked skill keeps a
description, so the agent can fire it autonomously — and other skills can reach it. You can still type its name: model-invocation always includes user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times — permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omitdisable-model-invocation, and write a model-facing description carrying the trigger branches (the pointer-writing rules inSKILL.mdapply in full). - A user-invoked skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load — you are the index that must remember it exists. Mechanics: set
disable-model-invocation: true; thedescriptionbecomes human-facing — a one-line summary, trigger lists stripped.
Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
Shared reference that two user-invoked skills both need can live in neither — with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
Splitting by invocation
The invocation cut of splitting (the sequence cut lives in SKILL.md): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own — a trigger word you actually use in your prompts — or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
Router skills
When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.