Skip to main content
A skill in the Context Base is a named domain expert captured as a document — the way your team thinks about a particular area, written down once and available to every build-side agent working on your project. shopware-headless-commerce, seo-optimizer, design-system-conventions, commerce-native-data-model. Each one brings in specialist perspective on a topic; the agent picks it up when a task touches that domain. Skills aren’t task procedures. “Build a category page” is a procedure — that’s a command. “Understand how we model products with variants and scopes” is a skill. The agent can build many different things while leaning on the same skill’s expertise. What makes a skill a skill is how it’s triggered. The agent auto-discovers relevant skills when it starts a task — if you ask it to improve a page’s metadata and there’s a skill named seo-optimizer, the skill gets pulled in on its own. You can also invoke a skill by name from the command menu when you want to force one. Skills and commands share the same content shape; the difference is commands only run when you call them by name.

​
What makes a good skill

A good skill is:
  • Scoped to a domain, not a task — shopware-headless-commerce is a domain; “build a category page” is a task. A domain covers many different tasks, and the agent should carry its expertise across all of them.
  • Specific to this project, not generic — agents already know TypeScript, REST, responsive patterns, and the basics of every framework. A skill earns its place by capturing something the agent wouldn’t guess: Shopware API quirks your team learned the hard way, the commerce-model choice that diverges from the default, the brand-specific constraint a fresh generalist would miss.
  • Descriptive of the domain’s patterns — explain what matters in this area, what gotchas exist, what the team has decided is right. Not a step-by-step “click here next”.
  • Written with why included — “use CategoryTile because it handles variant image selection and URL history correctly — building a new one reinvents both.” Domain context without the reasoning is a list of rules; with the reasoning, it’s understanding.
  • Scoped enough to name sharply — seo-optimizer is clear. all-our-best-practices is a catch-all that won’t get picked when it should.
The agent is the executor; the skill is the expert looking over its shoulder. If your notional expert is telling the agent things any competent engineer would already know, the skill isn’t earning its spot.

​
When skills help

Integration domains

shopware-headless-commerce, commercetools-api, contentful-content-modeling — the patterns, pitfalls, and vocabulary of each connected source system. Picked up whenever the agent touches that integration.

Cross-cutting concerns

seo-optimizer, accessibility-standards, performance-budget. Skills that apply across many task types — whenever the agent works on anything user-facing, it should have this expertise available.

Commerce model expertise

product-variants-and-scopes, pricing-and-currencies, multi-region-setup. How your team thinks about the commerce primitives specifically, not the abstract Frontic ones.

Technical specialties

frontend-design, nuxt-architect, api-design. Experts on a slice of the tech stack — framework idioms, architectural trade-offs, how the team solves problems at the code level. Not rules (those apply to every task); a perspective for when the area comes up.

​
When skills don’t help

Don’t write a skill for:
  • Specific procedures. “Build a category page”, “ship a hotfix”, “run an accessibility check” — these are tasks, not domains. They belong as commands (or as rules if they should apply to every task).
  • One-off domain knowledge. If you’ll never need the expertise again, write an ad-hoc prompt instead of a permanent skill.
  • Things the agent already knows well. The agent has broad general knowledge — “how to write TypeScript”, “make it responsive”, “follow REST conventions” don’t need skills. Write skills for the decisions, quirks, and constraints that are specific to your project.
  • Things that should be rules instead. Rules are constraints on every task; skills are domain expertise the agent consults when relevant.
  • Things that should be guides instead. A long reference document — an architecture write-up, a migration plan, a styleguide you haven’t distilled — belongs as a guide. Guides sit on the shelf until referenced; skills fire automatically when the domain comes up.

​
Writing a skill

Open Studio → Context → Skills in the admin app and click New Skill. Creation asks for two things:
  • Name — short, domain-flavored, triggerable in conversation. seo-optimizer is good; seo_stuff_v2_final is not. The name is how the agent decides whether a skill is relevant to the current task, so pick one a future teammate would recognize as a domain.
  • Description — one sentence about what the domain covers, shown in the skill list and used by the agent when deciding whether to pull the skill in.
Once the skill is created, you land in the editor where you write the domain expertise as Markdown. New skills start as Draft — flip the status to Active when the content is ready to apply. Only Active skills are read by agents. Skills can be scoped to this project (the default) or promoted to your organization so they apply across every project on your team.

​
Example: seo-optimizer

Here’s what a real domain skill might look like. The Markdown body is what the agent reads whenever a task touches SEO.
The agent reads this whenever it touches anything user-facing and brings the team’s SEO perspective into decisions — without you having to re-prompt the considerations every time.

​
How the agent picks a skill

Skills are discovered automatically. When you prompt an agent, it scans the available skills by name and description and pulls in whichever ones match the domain of the task. If you ask it to improve a page’s metadata and seo-optimizer exists, the skill gets read in before the agent starts. Multiple skills can apply to the same task — a product-page metadata task might pull in seo-optimizer and product-variants-and-scopes at once. You can also invoke a skill by name from the command menu — the same way you’d trigger a command. Useful when:
  • The domain overlap isn’t obvious and you want to force the skill
  • Multiple skills might match and you want a specific one to lead
  • You want the full content pulled in even though the agent wouldn’t pick it on its own
Use the seo-optimizer skill when reviewing this page’s metadata.
Skills can be forced; commands can only be forced. That’s the asymmetry.

​
Updating and iterating

Skills aren’t permanent. When your team’s thinking about a domain changes — a new platform version lands, a design decision supersedes an older one, a gotcha turns out not to matter anymore — edit the skill. Agents pick up the new version on their next session. Two tips for keeping skills healthy:
  • Keep a Gotchas section at the bottom. Every time someone runs into the same mistake twice in this domain, add it. This is the single highest-impact part of most skills.
  • Review regularly, or when something in the domain shifts. Walk through the skills and ask “is this still how we think about it?” Delete ones that aren’t. Update ones that are partially right.

​
How skills fit with the other Context Base types

All four live in the Context Base and all four shape how agents work, but the jobs are distinct: See Rules, Commands, and Guides for the other three.

Context Base

The mental model for the whole Context Base.

Rules

Always-on constraints on agent behavior.

Commands

Named shortcuts for recurring operations.

Guides

Reference documents the agent reads on demand.