Documentation

Skills

A skill is a self-contained piece of expertise – a single SKILL.md file that captures how to do one thing well. You write it once; the AI loads it on demand inside conversations or via the @skill() directive inside playbooks.

Promptmark’s skills follow the agentskills.io specification: YAML frontmatter with required name and description fields, followed by a markdown body. Skills you write in Promptmark are portable across any tool that adopts the spec.

When to Use a Skill

Skills sit between prompts and playbooks. Use one when:

  • The same expertise applies across many conversations or workflows (code review, summarization, research synthesis)
  • You want the AI to load it on demand rather than carrying it in every system prompt
  • You want the artifact to be portable – usable in conversations, playbooks, or any other agentskills-compatible tool

If you only need a fill-in-the-blank piece of text, a Template is simpler. If you need a multi-step workflow with branching and inputs, reach for a Playbook instead.

SKILL.md Structure

A SKILL.md file has two parts: YAML frontmatter and a markdown body.

markdown 
---
name: code-review
description: Performs systematic code review focused on quality, security, and maintainability.
license: MIT
---

# Code Review Skill

You are a senior engineer reviewing a code change. Apply these criteria in order:

## Quality
...

## Security
...

## Maintainability
...

Frontmatter Fields

Field Required Description
name Yes Slug-like identifier. Must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ – lowercase, alphanumerics and hyphens, no consecutive hyphens. Max 64 characters. Must be unique within your library.
description Yes One-line summary of what the skill does. Shown in the catalog and used by the AI to decide when to load the skill. Max 1,024 characters.
license No License identifier (e.g. MIT, Apache-2.0)
compatibility No Free-form compatibility note. Max 500 characters.
metadata No Free-form key-value map for your own use
allowed-tools No Free-form string per the spec. Experimental.

Body

The markdown body is the actual skill content – the instructions the AI receives when the skill is loaded. The agentskills.io spec recommends keeping bodies under 500 lines or 5,000 tokens for progressive disclosure. Promptmark warns when you exceed those caps but does not block save.

Total file size (frontmatter + body) is capped at 200 KB.

Creating a Skill

Three starter skills are seeded into every new account:

Starter Purpose
code-review Systematic code review across quality, security, maintainability
summarize-long-doc Summarize long documents with key points and action items
extract-action-items Pull action items, owners, and deadlines from meeting notes or emails

To author your own:

  1. Navigate to Skills in the sidebar
  2. Click New Skill
  3. Write your SKILL.md in the editor (frontmatter at the top, body below)
  4. Click Validate to check the file against the spec
  5. Click Save

The editor uses a YAML + markdown mixed-mode – frontmatter highlights as YAML, the body as markdown. A live counter shows characters, approximate tokens, and lines as you type.

Info
Skills are saved as drafts by default. Drafts won’t appear in conversations or resolve through @skill() – toggle off the Draft checkbox before publishing.

How Skills Load

Promptmark uses progressive disclosure – the AI sees a sanitized catalog of your skills, and loads the full SKILL.md only when relevant.

In Conversations

When a conversation starts, Promptmark injects a sanitized catalog of your published (non-draft) skills into the system prompt. Each entry has the skill name and description, capped at 200 characters per description for prompt-injection defense.

When the AI decides a skill is relevant, it calls the load_skill tool with the skill’s name. Promptmark returns the full SKILL.md content (frontmatter + body), capped at 64 KB. The AI uses that content for the rest of the conversation.

The catalog is capped at the first 100 published skills. If you have more than that, the AI will only see the first 100; reorder by publishing/unpublishing or pruning unused skills.

In Playbooks

Inside a playbook step, use the @skill(name) directive to load a skill at execution time:

markdown 
## STEP 2: Review the diff

@skill(code-review)

When the playbook executes step 2, Promptmark resolves code-review against your library, fetches its SKILL.md, and injects the full text as the step’s prompt. This is a sibling to @prompt(library:ID) – where @prompt() inlines a prompt artifact, @skill() inlines a skill artifact.

Drafts don’t resolve. Trying to reference an unpublished or missing skill produces an error visible in the execution log.

Versioning

Every save creates a snapshot. The skill’s editor page shows the current version count and lets you restore any previous version. Restoring creates a new snapshot of the current state first, so nothing is lost.

Safety Scanning

Skills run through the same safety scanning as prompts:

  • Layer 1 (Local) – PII, prompt injection, and secrets detection on every save
  • Layer 2 (Cloud moderation) – Violence, harassment, self-harm, dangerous content (when configured)

Each scan category uses the same trinary flag system as prompts (clean / has / had-acknowledged). See the Prompts & Templates guide for the full scan-flag model.

MCP Tools

Skills are fully manageable via MCP tools. AI assistants connected to your Promptmark MCP server can list, read, create, update, delete, and search your skills.

Tool Description
list_skills List your skills with optional search and pagination
get_skill Get the full SKILL.md (frontmatter + body) for a skill
create_skill Create a new skill from SKILL.md content (validated against the spec)
update_skill Update an existing skill (auto-snapshots before changes)
delete_skill Soft-delete a skill
search_skills Search skills by name, title, or description substring

For full MCP tool schemas, see the MCP Reference.

Tips

  • Keep skills focused. A skill should do one thing well. If yours grows past 500 lines, consider splitting it into two skills with different name slugs.
  • Description is doing real work. The AI uses the description to decide whether to load the skill. Write it as a one-sentence answer to “when should I use this?”.
  • Write skills in second person (“you are…”). They’re injected as the AI’s instructions, not as user input.
  • Publish before referencing. Drafts don’t resolve in conversations or playbooks – a forgotten draft toggle is the most common reason @skill() errors.

What’s Next