Agents & skills
Agents you write.Skills they keep.
Every agent is an OpenCode agent. It starts as a markdown file and grows into your own tools, plugins, models and a permission tree for each capability. A grant in your project config decides what it can reach: its machine, its connectors and channels, its secrets, its skills. A skill writes down how your company does one job. Both are files in your repo, and both get reviewed like code.
OpenCode-native · Versioned · Deny by default · Human-merged
- An agent is
- An OpenCode agent, plus its grants
- A skill is
- A folder with a SKILL.md inside
- Governance
- Deny by default
- Both land via
- A change request to main
01What an agent is
Two files. Nothing hidden behind them.
An agent lives in exactly two places. The markdown file holds how it thinks: its prompt, mode, model and permission tree. It is a stock OpenCode agent file, because Machine adds no dialect of its own. The block in your project config holds what it may touch. Nothing about an agent sits in a database you can’t read.
---description: "Generic Machine general knowledge worker. Hands-on, full tool access, handles coding / research / content / ops / data tasks end-to-end in an isolated session sandbox. Edit this file to specialize."mode: primarypermission: allow--- You are a **Machine general knowledge worker**. You are hands-on: you read, edit, run, search, fetch, andship. The session you are in is an isolated sandbox: anephemeral branch of this repo, your own /workspace, soyou can install, experiment, and recover freely. Only whatyou commit and push survives. ## How you work 1. **Understand first.** Read the relevant files, search the codebase or web, gather the context. Do not guess.2. **Plan briefly.** For non-trivial work, jot the approach to your todo list before touching anything.3. **Do the work.** Edit, write, run, fetch.4. **Verify.** Run the tests, hit the dev server, check the output. Whatever proves the change actually works.5. **Commit small, meaningful chunks.** Each commit leaves the repo in a working state.A trimmed excerpt of the default agent in every new Machine project.
# behavior lives in the .md. this block is governance only.default_agent: research-bot agents: research-bot: connectors: all secrets: all skills: all release-bot: # this one gets almost nothing, on purpose connectors: [github] secrets: [GITHUB_AGENT_TOKEN] # a grant you leave out resolves to none.# there is no implicit access. grant explicitly.- Put a behavior field in the governance block and the manifest rejects it, with an error that points you to the agent’s own .md file.
- Markdown is the floor, not the ceiling. The whole OpenCode surface sits next to it in the same repo: your own TypeScript tools, plugins that hook the runtime, model and provider config. An agent can pin its own model, or inherit the project default, then the account default, then the platform default.
- Every new project ships with two agents: a generalist that does the work, and memory-reflector, which curates the project brain.
02Scoped reach
Deny by default. Never above the human.
The grant covers the whole surface, not just tools: which sandbox image the agent boots, which connectors and channels it can call, which secrets it can receive, which skills it can load, and what it can do to Machine itself. Leave a grant out and the answer is no. Above all of it sits a ceiling no config can lift.
---description: "Reflects on recent project activity and curates the project brain. Runs on a cron and ends every run by opening a single change request."mode: primarypermission: edit: allow bash: "git *": allow "machine cr *": allow "machine sessions *": allow "*": ask---A real permission tree from an agent that ships today.
permission values
Three answers. That’s the whole list.
- allow
- Runs straight through. No prompt, no pause.
- ask
- Stops and asks a person. The session waits for your answer.
- deny
- Blocked. Not a warning, a wall.
Set one action for a whole capability (read, edit, bash, task, websearch, or reaching outside the workspace), or add glob rules under it so git push asks while everything else runs.
Rule 01
An agent never outranks its human
At session start, the agent gets what it declares, intersected with the role of whoever launched it. Grant an agent everything and it still gets exactly your permissions. No more, on any path.
Rule 02
Some things can’t be granted at all
Account administration (members, billing, creating projects) sits outside anything an agent can hold. No value you write in a file turns it on.
Rule 03
Secrets go by name, never by value
An agent’s block lists the secrets it may use by name. A session only receives the overlap between that grant and the role of the person who started it.
Rule 04
It can’t give itself a raise
An agent can edit the project config, because it’s a file. The edit only applies to sessions started after a person merges the change request, and the ceiling still holds even then.
03What a skill is
How your company does one job. Written down once.
A skill is a folder with a SKILL.md at its root. The frontmatter names it and says when to use it. The body is the procedure. Every session can load it, so what you explained to one agent in March is still true for every agent in November.
---name: agent-browserdescription: Browser automation CLI for AI agents. Use when the user needs to interact with websites: navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps. Triggers include "open a website", "fill out a form", "scrape data from a page", "test this web app", "login to a site".--- # agent-browser Fast browser automation CLI for AI agents. Chrome via CDPwith accessibility-tree snapshots and compact @eN refs. The CLI and a headless Chromium are **already installed**in this Machine sandbox and on $PATH, so you do not needto run any install step. ## Start here This file is a discovery stub, not the usage guide. Beforerunning any command, load the workflow content: ```bashagent-browser skills get core```An excerpt of a skill every new project ships with.
The description is the trigger
An agent decides whether to load a skill from its name and description alone. A vague description never fires, so a good one reads like the things a person would actually say.
More than prose
A skill folder can hold scripts, references and assets next to the markdown. The instructions and the tool they drive ship together, so one never drifts away from the other.
Granted, not global
An agent’s skills grant decides which skills it can load. Your finance agent doesn’t get the deployment runbook just because it happens to be in the repo.
10
Skills in a new project on day one
10
Platform skills in every session
19
Distinct skills, all told
2
Agents in every new project
04Everything is files
Your whole team lives in the diff.
Agents and skills aren’t rows in a table you can’t see. They’re markdown in the repo your cloud computer clones. Changing how your agents work is the same act as changing your code, and it gets the same review.
- your-company/
- project configwhat each agent may touch
- opencode/the runtime your agents think in
- agents/one OpenCode agent per file
- release-bot.mdan agent you wrote yourself
- memory-reflector.mdships in every project, curates the brain
- skills/one folder per skill
- agent-browser/SKILL.mdhow this company drives a browser
The editor writes a branch, not a row
Customize is read-only on purpose. Pressing “Create new” or “Edit” opens a session that edits the files on a branch and opens a change request for you to review and merge. No button quietly changes how an agent behaves tomorrow.
Agents improve themselves, and get reviewed for it
An agent can sharpen its own prompt, add a skill or tighten a permission rule. Each change is a commit on a branch, in a change request a person merges. Self-improvement, human-merged. An agent never merges its own.
Fork the whole team
Since it’s all text in one repo, you can branch every agent at once, try different grants, roll back, or hand the whole set to a new project. The configuration travels with the clone.
05Marketplace
Start from someone else’s work. Own it right away.
Browse agents, skills and whole projects, then add one to your project in a click. What arrives is files in your repo, not a dependency you rent. It’s on for every project and labelled beta, because sources and updates are still moving.
- 62 agents
- 61 skills
- 62 project templates
- Beta
Step 00
Find it
Browse without signing in. Machine ships its own registry: 62 agents, 61 skills and 62 project templates. You can switch on curated outside registries with one click. None of them load by default.
Step 01
Add it
One button starts an agent session. It reads the item’s source and merges what fits into your project’s own files, instead of dropping in a package and hoping.
Step 02
It sets itself up
If the item needs a key or a connected app, the agent hands you a fill-in link in the same turn. You never paste a credential into chat, and the agent never sees the value.
Step 03
You approve it
The session opens a change request. You see exactly which files are about to join your company, and you merge when you’re happy. Nothing lands without review.
What this isn’t: a package manager. There’s no lockfile, no version pin and no automatic update. An item you add becomes your own files, just like code you wrote. That’s a deliberate trade, and we’d make it again.
Build your team
Write it once.Every session knows it.
Agents and skills on one platform. Any model, your keys. Versioned and reviewable.
- OpenCode-native
- Versioned
- Deny by default
- Human-merged