Skip to content

Tohuhono/Oberon / .agents/skills/writing-for-agents

writing-for-agents

Verified

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

FileKindSize
SKILL-MECHANICS.mdmarkdown2.6 KB
SKILL.mdskill md10.7 KB
agents/openai.yamlconfig102 B

SKILL-MECHANICS.md

View on GitHub
# Skill mechanics

The skill-specific branch of [`writing-for-agents`](SKILL.md): 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: omit `disable-model-invocation`, and write a model-facing
  description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply 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`; the
  `description` becomes 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.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall