OpenCode Skills vs Commands, wann ihr welchen Baustein braucht

In unseren Dotfiles liegen vier kurze Befehle für OpenCode. /commit legt Commits nach Aufgabe an, jeden mit einer einfachen Zeile. /timelog schreibt drei Sätze für die Rechnung. /slack erzählt dem Team, was heute fertig wurde. /analyze nimmt ein fremdes Projekt unter die Lupe. Alle vier sind Commands, keiner ist ein Skill. Bei OpenCode Skills vs Commands entscheidet am Ende eine Frage, nämlich wer den Startschuss gibt. Hier steht, wie wir das entscheiden, mit den echten Dateien zum Kopieren und einem Skill, der aus einem der Commands entstehen kann.

Was OpenCode Skills und Commands unterscheidet

Ein Command ist ein gespeicherter Prompt mit einem Namen. Ihr tippt /timelog, OpenCode setzt Argumente und Shell Ausgaben ein und schickt den Text als euren Prompt ab. Ohne euren Aufruf passiert nichts. Wie ihr Commands anlegt, steht im Artikel OpenCode Commands erstellen.

Ein Skill ist eine Anleitung mit einer Beschreibung. OpenCode zeigt dem Modell bei jedem Schritt eine Liste der Skills mit ID, Name und Beschreibung. Passt eine Beschreibung zur Aufgabe, lädt der Agent die Anleitung über das skill Tool in die Unterhaltung. Der volle Text kommt also erst in den Kontext, wenn er gebraucht wird.

Dazu kommt ein dritter Baustein, der in dieser Frage oft vergessen wird. Die AGENTS.md gilt immer. OpenCode lädt sie beim Start, erst die globale Datei, dann die aus dem Projekt.

• AGENTS.md gilt in jeder Session.
• Command läuft, wenn ihr es sagt.
• Skill kommt dazu, wenn die Aufgabe es verlangt.

Frage	Command	Skill	AGENTS.md
Wer löst aus	Ihr mit /name	Der Agent, wenn die Beschreibung passt, oder ihr mit @skill-id	Niemand, sie wird beim Start geladen
Wo liegt es	.opencode/commands/ oder ~/.config/opencode/commands/	.opencode/skills/ oder ~/.config/opencode/skills/	Im Projekt oder unter ~/.config/opencode/
Was steht im Kontext	Der Prompt, erst beim Aufruf	Immer ID, Name und Beschreibung, der volle Text erst beim Laden	Der ganze Text in jeder Session
Argumente	$ARGUMENTS, $1, $2	Keine	Keine
Shell Ausgabe vor dem Prompt	Ja, mit Ausrufezeichen und Befehl in Backticks	Nein, der Agent führt Skripte selbst aus	Nein
Begleitdateien	Keine	Skripte, Referenzen und Vorlagen im Skill Ordner	Keine
Agent und Modell festlegen	Ja, mit agent, model und subagent	Nein, der Text kommt in die laufende Unterhaltung	Nein
Passt für	Abläufe mit festem Zeitpunkt	Wissen, das mitten in einer Aufgabe gebraucht wird	Regeln, die immer gelten

Die OpenCode Commands aus den NCA Dotfiles

Die Dateien liegen offen im NCA Dotfiles Repository auf GitHub. Ein make install verlinkt den Ordner opencode/commands/ nach ~/.config/opencode/commands/. Damit gelten die Commands global, also in jedem Projekt. Daneben liegt eine kurze AGENTS.md mit zwei Regeln.

# OpenCode Global Rules

- Only commit when the user explicitly says to.
- Always respond in English, regardless of the language the user writes in.

Zwei Zeilen, die in jeder Session gelten. Mehr steht dort bewusst nicht. Alles Weitere liegt in den Commands.

Der commit Command

---
description: NCA simple commits
---

- commit single files grouped by task single simple lines
- start with capital letter end with fullstop.

Ein Commit verändert die Historie. Deshalb steht in der AGENTS.md, dass der Agent nur auf ausdrückliche Ansage committet. Der Command ist diese Ansage und bringt das Format gleich mit. Ein Skill würde dem Agent das Format beibringen, den Zeitpunkt aber offen lassen. Bei einem Commit wollen wir den Zeitpunkt selbst bestimmen. Dass die Regel wirkt, zeigt die Historie des Repositories. Der Commit für den Slack Command heißt Add Slack command for team updates., mit großem Anfangsbuchstaben und Punkt am Ende.

Der timelog Command

---
description: NCA timelog
---

was haben wir heute gemacht in 3 kurzen einfach sätzen für eine rechnung kein technisches blabla

Format und Länge als Beispiel

Passwortschutz in Tests verbessert.
Rauch Tests für Live-Umgebung eingerichtet.
Live-Ausführung auf sichere Tests umgestellt.

Hier zählt der Moment. Der Command braucht die laufende Session als Stoff, denn nur dort steht, was heute passiert ist. Das Beispiel am Ende legt Format und Länge fest. Heraus kommen drei Sätze ohne Technik, die direkt in die Rechnung passen.

Der slack Command

---
description: NCA team update for Slack
---

schreibe einen kurzen Text fürs Team was heute gemacht wurde in einfachem Deutsch

- beginnt mit "Heute habe ich ..."
- kurze einfache Fließsätze
- Perspektive ist immer "ich", nie "wir"
- keine Doppelpunkt-Konstruktionen und keine Labels, nur die erklärenden Sätze
- kein technisches Blabla, erzähle was erreicht wurde nicht wie

Gleiche Session, anderer Leser. Die Rechnung bekommt drei nüchterne Sätze, das Team eine kurze Erzählung in der Ich Form. Zwei Commands holen aus derselben Arbeit zwei Texte. Wann sie dran sind, wissen wir selbst am besten, nämlich wenn die Arbeit getan ist.

Der analyze Command

---
description: NCA analyse
---

Analyse the given project
Target
- Find legacy code and problems
- Find security problems
- Check documentation and readme file
- Is a framework used and what would we prefer for techstack
- When python flask
- When javascript AstroJS
- Frontend tailwindcss
- Detect vanilla ai slop code

Auch hier geben wir den Start, wenn ein fremdes Projekt auf dem Tisch liegt. Trotzdem ist dieser Command anders als die drei davor. In ihm steckt Wissen. Er legt fest, was wir als Problem werten und welchen Stack wir bevorzugen. Dieses Wissen wäre auch an anderen Stellen nützlich, etwa beim Start eines neuen Projekts oder in einem Review. Dort kennt der Agent es nur, wenn vorher jemand /analyze tippt. Das macht ihn zum Kandidaten für einen Skill. Mehr zum letzten Punkt der Liste steht im Artikel über AI Slop in Pull Requests.

Wann ein OpenCode Command die richtige Wahl ist

Ein Command passt, sobald einer dieser Punkte zutrifft.

• Ihr kennt den Moment. Feierabend, vor dem Push, nach dem Review. Den Zeitpunkt bestimmt ihr, der Agent muss ihn nicht erraten.
• Die Aufgabe hat Nebenwirkungen. Ein Commit, eine Nachricht oder ein Deployment sollen nie von selbst starten.
• Ihr braucht Argumente. Aus /review src/auth.ts wird ein Prompt für genau diese Datei.
• Der Prompt braucht frische Fakten. Ein Shell Block holt den Diff oder das Testergebnis in den Prompt, bevor das Modell ihn sieht.
• Agent oder Modell sollen feststehen. Ein Command kann einen Agent wählen, ein Modell setzen und im Hintergrund laufen.

Ein Beispiel, das alle diese Felder nutzt, sieht so aus.

---
description: Review a file against the last commits
agent: plan
subagent: true
---

Recent commits:

!`git log --oneline -5`

Review $ARGUMENTS for bugs and missing tests.

Das Feld für den Hintergrund heißt in der aktuellen Doku subagent. Das ältere subtask gilt als veraltet und wird weiter akzeptiert. Was sich sonst geändert hat, steht im Artikel zum Umstieg auf OpenCode 2.

Ein Punkt verdient Vorsicht. Shell Blöcke laufen, sobald OpenCode den Command auswertet, und zwar außerhalb der Permissions des Agents. Übernehmt Commands deshalb nur aus Quellen, denen ihr vertraut. Commands für das Team gehören ins Repository und laufen durch denselben Review wie der Code. Wie ihr den Agent selbst absichert, zeigen die OpenCode Permissions. Alle Felder erklärt die OpenCode Doku zu Commands.

Wann ein OpenCode Skill die richtige Wahl ist

Ein Skill passt, wenn der Agent etwas wissen muss und ihr in dem Moment gar nicht daran denkt.

• Das Wissen wird mitten in einer Aufgabe gebraucht. Der Agent schreibt einen Test, bereitet ein Release vor oder wählt ein Framework. Die Anleitung dazu soll er selbst holen.
• Es gehören Dateien dazu. Skripte, Referenzen und Vorlagen liegen neben der SKILL.md. Der Agent liest sie erst, wenn die Anleitung es verlangt.
• Der Text ist zu lang für die AGENTS.md. Dort würde er jede Session belasten. Als Skill steht dauerhaft nur die Beschreibung im Kontext.
• Im Team laufen mehrere Coding Agents. OpenCode liest zusätzlich die Ordner .claude/skills und .agents/skills. Ein Skill, der dort liegt, muss für OpenCode nicht doppelt gepflegt werden.
• Mehrere Projekte sollen dasselbe Wissen nutzen. Über das Feld skills in der Konfiguration bindet ihr weitere Ordner oder einen Katalog per HTTP ein.

Bei uns sind die Skills aus dem Cypress AI Toolkit ein gutes Beispiel. Niemand tippt vor jedem Test einen Befehl. Der Agent braucht das Wissen von selbst, sobald er einen Test schreibt. Was das in der Praxis ändert, steht im Artikel zum Cypress AI Toolkit.

Die Beschreibung ist der Auslöser. Das Modell sieht von einem Skill zunächst nur ID, Name und Beschreibung. Schreibt deshalb hinein, wann der Skill gebraucht wird, und bleibt dabei konkret. Ein Skill ohne Beschreibung wird dem Modell gar nicht angezeigt. Alle Regeln stehen in der OpenCode Doku zu Skills.

So wird aus dem analyze Command ein OpenCode Skill

In den Dotfiles liegt heute nur der Command. Der Skill hier ist ein Beispiel für diesen Artikel und zeigt, wie der Umbau aussehen kann. Das Wissen wandert in einen eigenen Ordner.

~/.config/opencode/skills/
└── nca-analyse/
    ├── SKILL.md
    └── references/
        └── techstack.md

Die SKILL.md beschreibt, wann der Skill gebraucht wird und wie der Agent vorgeht.

---
name: NCA Analyse
description: Analyse a project for legacy code, security problems, missing documentation and AI slop. Use when reviewing an unknown codebase or choosing a tech stack.
---

## Workflow

1. Read the README and the documentation first.
2. Find legacy code and security problems.
3. Detect vanilla AI slop code.
4. Read `references/techstack.md` before recommending a framework.
5. Report findings as a short list with file, problem and suggestion.

Die Vorgaben zum Stack liegen in references/techstack.md. Der Agent liest die Datei erst in Schritt vier.

# Preferred tech stack

- Python projects use Flask
- JavaScript projects use Astro
- Frontend uses Tailwind CSS

Die ID des Skills kommt aus dem Pfad und lautet nca-analyse. Der Name im Frontmatter ist nur die Anzeige. Der Command bleibt als kurzer Auslöser bestehen und verweist auf den Skill.

---
description: NCA analyse
---

Load the skill nca-analyse and analyse $ARGUMENTS.

Damit gibt es zwei Wege zum selben Wissen. Ihr startet die Analyse bewusst mit /analyze. Und der Agent kann den Skill selbst laden, wenn er in einem Review oder bei einer Frage zum Stack darauf stößt. Soll der zweite Weg zu bleiben, versteckt ihr den Skill vor dem Modell.

---
name: NCA Analyse
description: Analyse a project for legacy code, security problems, missing documentation and AI slop.
metadata:
  opencode/autoinvoke: false
---

Der Skill bleibt registriert. Ihr ladet ihn dann von Hand, indem ihr ihn im Prompt mit @nca-analyse erwähnt.

OpenCode Skill oder Command in fünf Fragen entscheiden

Geht die Fragen von oben nach unten durch. Das erste Ja entscheidet.

Frage	Bei Ja
Gilt es in jeder Session ohne Ausnahme	AGENTS.md
Verändert es etwas außerhalb der Session, etwa durch Commit, Nachricht oder Deployment	Command
Wisst ihr selbst am besten, wann es dran ist	Command
Soll der Agent mitten in einer Aufgabe selbst darauf kommen	Skill
Gehören Skripte, Vorlagen oder lange Referenzen dazu	Skill

Auf die NCA Dotfiles angewendet sieht das so aus.

Datei	Baustein	Warum
AGENTS.md	Regel	Zwei Zeilen, die immer gelten
commit.md	Command	Nebenwirkung, läuft nur auf Ansage
timelog.md	Command	Fester Moment, braucht die laufende Session
slack.md	Command	Fester Moment, anderer Leser
analyze.md	Command und Kandidat für einen Skill	Enthält Wissen zum Stack, das auch an anderen Stellen hilft

Typische Fehler mit OpenCode Skills und Commands

• Alles steht in der AGENTS.md. Jede Zeile dort kostet in jeder Session Kontext. Lange Anleitungen für einzelne Aufgaben gehören in einen Skill.
• Der Skill hat keine Beschreibung. Dann zeigt OpenCode ihn dem Modell nicht an und er wird nie von selbst geladen.
• Die Beschreibung ist zu allgemein. Der Agent lädt den Skill dann zu oft oder gar nicht. Schreibt hinein, bei welcher Aufgabe er gebraucht wird.
• Ein Skill löst Nebenwirkungen aus. Was committet, verschickt oder ausrollt, gehört in einen Command oder bekommt opencode/autoinvoke: false.
• Wissen steckt nur in einem Command. Der Agent kennt es erst nach dem Aufruf. Braucht er es auch an anderen Stellen, zieht es in einen Skill um.
• Name und ID werden verwechselt. Die ID eines Skills kommt aus dem Pfad und unterscheidet Groß und Kleinschreibung. Der Name im Frontmatter ist nur die Anzeige.
• Fremde Commands landen ungeprüft im Projekt. Ihre Shell Blöcke laufen ohne Rückfrage des Agents. Lest sie vorher.

Wie wir Teams bei Commands, Skills und Guardrails helfen

OpenCode ist bei uns der Coding Agent im Alltag. Commands und Skills sind zwei kleine Teile eines Setups, zu dem Regeln, Rechte und Quality Gates gehören. Warum dieses Drumherum mehr ausmacht als das Modell, beschreibt der Artikel zum Agent Harness. Warum Leitplanken mit jedem Modell wichtiger werden, steht in KI Guardrails und bessere Modelle. Wie der Agent in der Pipeline läuft, zeigt OpenCode GitHub Action einrichten.

Welche Modelle zu welcher Aufgabe passen, vergleichen wir bei den Vibe Coding Modellen. Pipelines für KI Code beschreiben die Vibe Coding CI/CD Pipelines. Im NCA KI Workshop für Developer baut euer Team eigene Commands, Skills und Guardrails. Begleitung im Projekt gibt es in der Vibe Coding Beratung.

Häufige Fragen zu OpenCode Skills und Commands

Was ist 2026 der Unterschied zwischen OpenCode Skills und Commands?

Ein Command startet, wenn ihr ihn mit einem Schrägstrich tippt. Ein Skill wird vom Agent geladen, wenn seine Beschreibung zur Aufgabe passt. Der Command ist ein gespeicherter Prompt mit Argumenten und Shell Ausgaben. Der Skill ist eine Anleitung mit eigenem Ordner für Skripte und Referenzen. Beide sind Markdown Dateien und lassen sich im Repository teilen.

Wann nutze ich 2026 einen OpenCode Command statt eines Skills?

Nehmt einen Command, wenn ihr den Zeitpunkt selbst bestimmt. Das gilt für Commits, Zeiterfassung, Team Updates und alles mit Nebenwirkungen. Auch Aufgaben mit Argumenten oder mit frischen Shell Ausgaben im Prompt gehören in einen Command. Bis zum Aufruf belegt er keinen Platz im Kontext, erst dann wird sein Text zum Prompt.

Wann lohnt sich 2026 ein OpenCode Skill?

Ein Skill lohnt sich für Wissen, das der Agent mitten in einer Aufgabe braucht, ohne dass ihr daran denkt. Typisch sind Abläufe für Releases, Konventionen für Tests oder Vorgaben zum Stack. Gehören Skripte, Vorlagen oder lange Referenzen dazu, ist der Skill Ordner der richtige Platz. Im Kontext steht dauerhaft nur die kurze Beschreibung.

Kann der Agent 2026 einen OpenCode Skill von selbst laden?

Ja. OpenCode zeigt dem Modell bei jedem Schritt eine Liste der erlaubten Skills mit ID, Name und Beschreibung. Passt eine Beschreibung zur Aufgabe, ruft das Modell das skill Tool mit der ID auf. Erst dann kommt der volle Text in die Unterhaltung. Einen Command startet der Agent nicht von selbst, den tippt ihr mit dem Schrägstrich.

Wo liegen 2026 OpenCode Skills und Commands?

Commands liegen im Projekt unter .opencode/commands und global unter ~/.config/opencode/commands. Skills liegen unter .opencode/skills und global unter ~/.config/opencode/skills, am besten als Ordner mit einer SKILL.md. OpenCode liest zusätzlich .claude/skills und .agents/skills. Bei gleichem Namen ersetzt die Datei im Projekt die globale.

Kann ich einen OpenCode Skill von Hand laden?

Ja. Erwähnt den Skill im Prompt mit einem At Zeichen und seiner ID, zum Beispiel @git-release. OpenCode fügt die Anleitung dann in die Unterhaltung ein. Das ist auch der Weg für Skills, die ihr mit autoinvoke false vor dem Modell versteckt habt. Sie bleiben registriert und lassen sich über ihre ID weiter laden.

Wie verhindere ich, dass der Agent einen Skill von selbst lädt?

Setzt im Frontmatter unter metadata den Wert opencode/autoinvoke auf false. Der Skill verschwindet dann aus der Liste, die das Modell sieht, bleibt aber registriert. Strenger sind Permissions. Mit deny wird der Skill versteckt und jedes Laden abgelehnt. Mit ask bleibt er sichtbar und OpenCode fragt vor dem Laden nach.

Kosten Skills Kontext, auch wenn sie nicht genutzt werden?

Ja, aber wenig. Für jeden erlaubten Skill mit Beschreibung stehen ID, Name und Beschreibung in der Liste für das Modell. Der eigentliche Text und die Begleitdateien kommen erst beim Laden dazu. Viele Skills mit langen Beschreibungen summieren sich trotzdem. Haltet die Beschreibung deshalb kurz und genau.

Kann ein OpenCode Command einen Skill nutzen?

Ja. Ein Command ist ein normaler Prompt. Nennt ihr darin einen Skill mit seiner ID, kann der Agent ihn über das skill Tool laden. So bleibt der Command ein kurzer Auslöser mit Argumenten und das Wissen liegt gepflegt im Skill. Voraussetzung ist, dass die Permissions des Agents diesen Skill erlauben.

Was gehört in die AGENTS.md statt in einen Skill?

In die AGENTS.md gehört alles, was in jeder Session gilt. Das sind Build Befehle, Konventionen und harte Regeln wie das Verbot, ohne Ansage zu committen. OpenCode lädt die Datei beim Start. Lange Anleitungen für einzelne Aufgaben sind dort zu teuer, weil sie jede Session belasten. Die sind in einem Skill besser aufgehoben.

Liest OpenCode auch Skills aus dem Ordner .claude/skills?

Ja. OpenCode durchsucht neben den eigenen Ordnern auch .claude/skills und .agents/skills, im Projekt und global. Bei gleicher ID gewinnen die OpenCode Ordner, weil sie später registriert werden. Für Regeln gilt das nicht. OpenCode erkennt in Version 2 nur die AGENTS.md und nutzt keine CLAUDE.md als Ersatz.

Warum taucht mein OpenCode Skill nicht auf?

Meist fehlt die Beschreibung, denn Skills ohne description zeigt OpenCode dem Modell nicht an. Prüft außerdem den Dateinamen. In einem Unterordner muss die Datei genau SKILL.md heißen. Die ID kommt aus dem Pfad und unterscheidet Groß und Kleinschreibung. Weitere Ursachen sind autoinvoke false, eine Permission mit deny oder ein später geladener Skill mit derselben ID.