> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frontic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

A **skill** in the [Context Base](/context-base/overview) 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](/context-base/commands). "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](/context-base/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

<CardGroup cols={2}>
  <Card title="Integration domains" icon="plug">
    `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.
  </Card>

  <Card title="Cross-cutting concerns" icon="arrows-left-right-to-line">
    `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.
  </Card>

  <Card title="Commerce model expertise" icon="boxes-stacked">
    `product-variants-and-scopes`, `pricing-and-currencies`,
    `multi-region-setup`. How your team thinks about the commerce
    primitives specifically, not the abstract Frontic ones.
  </Card>

  <Card title="Technical specialties" icon="code">
    `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.
  </Card>
</CardGroup>

## 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](/context-base/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](/context-base/rules) instead.** Rules are constraints on every task; skills are domain expertise the agent consults when relevant.
* **Things that should be [guides](/context-base/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**.

<Screenshot name="context-base/skills-new-skill-dialog" caption="New Skill — name and description at creation time" alt="Studio New Skill dialog with name and description fields and a Create button" />

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](/context-base/overview#document-scoping-project-vs-global) 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.

```markdown theme={"theme":"css-variables"}
# seo-optimizer

What you should bring to any task that affects user-facing pages
or URL structure.

## What matters for us

- **Canonical URLs are authoritative.** Every listing and page must
  produce one canonical URL per record. Duplicate content (same
  record accessible via two URLs) gets us penalized. When you see a
  case where a record might resolve two ways, flag it.
- **Hreflang on translated pages is non-negotiable.** Every locale
  variant of a page must reference the other locales' URLs via
  `<link rel="alternate" hreflang="…">`. The Frontic built-in SEO
  composite handles this; don't build it yourself.
- **Redirects, not 404s, on withdrawn content.** A deleted category
  should 302-redirect, not 404. Search engines stop serving the URL
  after seeing 302s over time; 404s keep the URL surfaced as
  broken.
- **Structured data where it earns its keep.** Product pages get
  `Product` schema; category pages get `ItemList`; content pages
  don't need structured data unless they're articles.

## Patterns we've settled on

- The SEO composite on every page block handles title, description,
  canonical, and hreflang. Use it.
- Titles follow the pattern `{page title} | {site name}`. Brand in
  the title helps CTR in search results.
- Descriptions are capped at 155 characters. Longer gets truncated.

## Gotchas

- Don't set `og:image` in a block-level composite — the page-level
  SEO composite pulls the right image from the record. Setting both
  produces conflicting og tags.
- Query-string filters (`?size=L&color=red`) must not be canonical.
  Set canonical to the filter-less URL or search engines index
  every combination.
- Locale-only URL variants (`/en/…` vs `/de/…`) use hreflang, not
  canonical. Canonical is only for duplicate-content cases.
```

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](/context-base/commands). 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:

|              | Triggered by                          | Shape                | Example                      |
| ------------ | ------------------------------------- | -------------------- | ---------------------------- |
| **Skills**   | A matching domain (or forced by name) | Domain expertise     | `seo-optimizer`              |
| **Rules**    | Always active                         | Always-on constraint | `product-images-through-cdn` |
| **Commands** | Forced by name only                   | Task procedure       | `code-review`                |
| **Guides**   | Explicitly referenced                 | Reference document   | `authentication-flow`        |

See [Rules](/context-base/rules), [Commands](/context-base/commands), and [Guides](/context-base/guides) for the other three.

## Related

<CardGroup cols={2}>
  <Card title="Context Base" icon="brain" href="/context-base/overview">
    The mental model for the whole Context Base.
  </Card>

  <Card title="Rules" icon="gavel" href="/context-base/rules">
    Always-on constraints on agent behavior.
  </Card>

  <Card title="Commands" icon="terminal" href="/context-base/commands">
    Named shortcuts for recurring operations.
  </Card>

  <Card title="Guides" icon="book" href="/context-base/guides">
    Reference documents the agent reads on demand.
  </Card>
</CardGroup>