Skills

Skills are short Markdown playbooks an AI agent follows automatically when their description matches the task. A skill is one document: a small YAML frontmatter on top, the instructions you want the AI to follow underneath.

You don’t have to learn the format by hand. Novamira ships with a built-in skill-creator: tell your AI “create a skill that does X” and the agent writes the first draft for you. You review and save it from the Novamira admin.

Skills live inside WordPress. You write or upload them from the Novamira admin, they stay with your site, and any AI agent connected through Novamira loads them when their description matches your prompt. Until then, the body sits dormant.

Skills are stored in WordPress and shared across every administrator who connects an AI agent to this site. Author once, every admin’s AI follows them.

When the agent loads a skill

At session start, the agent reads only the description field of every available skill. Bodies stay dormant.

When your prompt matches one of those descriptions, the agent loads the matching body into its context and follows it. This keeps the cost of many skills low: descriptions are cheap to skim, bodies are loaded on demand.

Two skills with overlapping descriptions can both fire on the same prompt. The agent reads both bodies and decides how to combine them.

Anatomy of a skill

The frontmatter is a small YAML block at the top of the document:

  • name: a slug used internally. Auto-derived from the title server-side, so you can leave it out.
  • description: a one-line trigger blurb. This is the only field the agent reads to decide whether to fire the skill, so write it as if you were describing the skill to a stranger who has not seen the body.
  • enable_prompt: expose the skill as an MCP prompt the user can invoke directly from the AI client (default true).
  • enable_agentic: include the skill in the catalog the agent reads automatically (default true).

The body is plain Markdown. Hard limit: 1 MB. Practically, keep it well under 5,000 words. Every word in the body competes with your prompt and the rest of the conversation for the agent’s context.

A minimal skill:

---
name: my-first-skill
description: Trigger blurb that decides when the agent loads this skill.
---

# My first skill

Whatever instructions you want the agent to follow when it fires.

Examples

Three concrete skills to make the shape tangible.

Agentic only: page naming conventions

Fires automatically whenever the AI creates or renames a page. You never invoke it. The agent just follows the conventions because the description matches.

---
name: page-naming-conventions
description: How to name new pages on this site (titles, slugs, parent pages, SEO meta). Use whenever you create or rename a page.
enable_agentic: true
enable_prompt: false
---

# Page naming conventions

Titles: sentence case, no trailing site name (the theme appends it).
Slugs: lowercase, hyphen-separated, drop articles (a, an, the).
Parent pages: services under /services/, case studies under /work/, everything else top-level.
SEO meta description: always present, 140 to 155 characters.
Featured image: warn before publish if missing.

Prompt only: weekly site audit

Runs only when you invoke it from the AI client’s prompt menu. Not relevant to most prompts, so it stays out of the agent’s automatic catalog.

---
name: weekly-site-audit
description: Walk through a weekly site check: broken internal links, missing alt text, slow pages, recent security notices.
enable_prompt: true
enable_agentic: false
---

# Weekly site audit

Run these checks in order, reporting findings as you go.

1. Broken internal links: scan published post_content for hrefs to this domain, HEAD-check each one.
2. Missing alt text: list attachments used in published posts with empty alt.
3. Slow pages: top 10 slowest URLs from any available logs.
4. Recent security notices in WordPress core, plugins, themes.

Both modes: brand voice excerpts

The agent applies it when your prompt asks to revise excerpts. You can also invoke it explicitly when you want to bulk-process a set of posts.

---
name: brand-voice-excerpts
description: Rewrite WordPress post excerpts in the Acme brand voice (concise, second-person, action-oriented). Use when the user asks to revise excerpts, fix tone, or generate excerpts where missing.
enable_prompt: true
enable_agentic: true
---

# Brand voice excerpts

Voice rules:
- Second person ("you", "your"). Never first person.
- 1 to 2 sentences, under 160 characters.
- Action-oriented: open with a verb where possible.
- No marketing adjectives ("amazing", "powerful").

Process: read the post body, summarize the single most useful takeaway, restate in voice.

Two modes: agentic and prompt

The two enable_* fields control how a skill becomes available. They are independent: a skill can be agentic, prompt, both, or neither (though neither makes no practical sense).

Agentic (enable_agentic: true). The skill’s description goes into the catalog the agent reads automatically. When your prompt matches the description, the agent decides on its own to load the body. You do not have to know the skill exists. Use this when you want a behavior to fire every time for a given kind of task. Example A above is a good fit.

Prompt (enable_prompt: true). The skill is exposed as an MCP prompt: a named entry the AI client surfaces in its prompt menu or slash-command list. You invoke it explicitly when you want it. The body loads only on that invocation. Use this for workflows you trigger deliberately, like a weekly audit. Example B above fits.

Both (default). The skill works either way: the agent fires it automatically when the description matches, and you can also invoke it explicitly. Use this when you are unsure or want flexibility. Example C above fits.

The built-in skill-creator

Novamira ships with a built-in skill named skill-creator. It is itself an agentic skill: its description matches phrases like “create a skill”, “make a skill”, “add a skill for X”.

The fastest way to learn the format is to ask the agent to create one. The agent loads skill-creator, follows its guidance, and writes a first draft you can review and save from the admin. The meta-skill writes the skills.

Writing good skills

A few principles, condensed from the built-in skill-creator.

The description is the trigger. Write it so a stranger can tell at a glance what the skill does and when to invoke it. Include the phrases your team actually says. A bad description: “Helps with posts.” A better one: “Bulk-rewrite WordPress post excerpts in the Acme brand voice. Use when the user asks to revise excerpts across many posts, fix on-brand voice, or generate excerpts where they are missing.”

Be concise. Every word in the body competes with your prompt and the rest of the conversation for the agent’s context. The AI is already a capable WordPress operator. Cut anything it can infer from inspecting the site or running a quick probe.

Match specificity to fragility. When several approaches are valid and decisions depend on context, write prose. When a preferred pattern exists with acceptable variation, show annotated examples. When the task is destructive or has one correct sequence (irreversible migrations, fee calculations, anything you cannot undo), spell out the exact steps and add explicit “do not deviate” wording.

Skills are flat. Everything the agent needs lives in the single body. No bundled scripts, no references/ directories, no companion assets. If you find yourself wanting to attach files, the skill is probably trying to do too much.

Managing skills from the admin

Open Novamira > Skills in the WordPress admin to see all skills on this site. From there you can upload a Markdown file with frontmatter, create a new skill inline, edit an existing one, enable or disable it without deleting, and delete it permanently.

The enable/disable switch is useful when iterating: a disabled skill stays in the admin but is hidden from the agent, so you can pause a skill that is misbehaving without losing the body.

When to consider Pro

Free Skills let you write Markdown playbooks for any recurring task you want the AI to handle consistently on your site. The skills you write capture knowledge specific to your project: your naming, your workflows, your conventions.

Novamira Pro is a different proposition. It is a complete strategy our team builds and maintains for the parts of WordPress where AI agents struggle most: page builders, content modeling, and other complex integrations. Pro combines specialized abilities (real PHP tools that act on those integrations directly) with skills we author and keep updated, so the agent has both the right tools and the right playbook. Pro also adds memory between sessions, so the AI remembers project decisions across conversations.

In short: Free Skills are how you teach the agent things specific to your site. Pro is a curated, team-maintained strategy for the parts of WordPress that are hardest to get right. See what Pro adds →

Limits and notes

The body has a hard limit of 1 MB. In practice, keep it well under 5,000 words. Most skills fit in 200 to 800 words.

Skills are a single Markdown document. No bundled scripts, references, or assets. If you need to share helper code, save it as a sandbox file and reference it from the skill body by path.

Skills are site-wide. Every administrator’s AI on this site sees the same set of skills.

The body is loaded as-is into the agent’s context. The agent decides how to follow it. Skills are guidance, not enforcement: think of them as instructions to a careful operator, not as rules the runtime enforces.