Skip to main content
Agent skills are reusable instruction packs attached to an agent. They help an agent do specific work more consistently without bloating its always-on instructions. A good skill should do at least one of these well:
  • Give the agent knowledge or logic it would not reliably infer on its own
  • Load context only when needed instead of expanding the agent’s base instructions
  • Make repeated work more consistent with saved instructions, scripts, references, or templates
If something is just a long wall of obvious guidance that should apply in every conversation, it usually belongs in the agent’s instructions, not a skill.

​
What Is A Skill?

A skill is a reusable folder of instructions and resources that an agent can load when it is relevant to the task. Every skill includes a required SKILL.md file. Some skills also include helper files such as:
  • scripts/ for deterministic code
  • references/ for longer supporting documentation
  • assets/ for templates or static files
In Markifact, skills are scoped to the agent you create them on. That makes them useful for building agents with distinct operating styles or repeatable job-specific playbooks. Markifact also provides read-only system skills. These are built in by Markifact and available where relevant.

​
Skills Vs. Instructions Vs. Tools

Use this when…Best fit
The rule should apply in every conversationAgent instructions
The agent just needs the ability to take an actionTool
The agent needs reusable process, context, or structure for a specific kind of taskSkill
Examples:
  • “Always be concise and professional” → agent instructions
  • “Pull a Meta Ads report” → tool usage
  • “Build our weekly client reporting deck in our standard format” → skill

​
When To Create A Skill

Create a skill when you have a repeatable task that should be handled the same way every time. Common cases:
  • A multi-step process the agent should follow consistently
  • A response format, template, or checklist you want reused
  • Domain knowledge that is too specific or too long for the main agent instructions
  • Exact logic that is better handled by a script than by free-form reasoning
  • Work that a single agent will perform repeatedly over time
Good examples:
  • Weekly performance summary playbook
  • Brand voice and post formatting rules for one account
  • A QA checklist for campaign launches
  • A reporting skill with a helper script to shape output data
Not every repeated request needs a skill. If it is a one-off task or a universal rule for the agent, keep it out of the skill layer.

​
How Skills Work In Markifact

At a high level, the flow looks like this:
  1. An agent has access to a set of skills.
  2. The agent sees the available skill names and descriptions first.
  3. When a skill looks relevant, the agent reads that skill’s SKILL.md and any supporting files it needs.
  4. The agent follows those instructions while completing the task.
This on-demand loading matters. It keeps the agent’s always-on context lighter than dumping every process into the main instructions.
Skills are for reusable task-specific guidance. They are not a replacement for your agent’s universal identity, tone, or safety rules.

​
Creating Skills

From an agent’s Skills page, Markifact currently supports two practical creation flows:

​
1. Create With AI

Use New Skill → Create with AI when you want the agent to help you design the skill. This is the best option when:
  • The scope is still fuzzy
  • You want help turning a workflow into good skill instructions
  • The skill may need extra files, structure, or iteration

​
2. Write Instructions

Use New Skill → Write Instructions for simple instruction-only skills. You provide:
  • Name
  • Description
  • Instructions
This is the fastest path for lightweight skills such as formatting rules, playbooks, or checklists.
In the Write Instructions flow, the Name and Description fields are already captured separately by Markifact. The Instructions field should contain only the body of the skill, not another copy of the name, description, or YAML frontmatter.
Start with a simple instruction-only skill when possible. If the task later needs code, reference docs, or templates, you can expand the skill over time.

​
What’s Inside A Skill?

Most skills are just a well-written SKILL.md, but a richer skill can look like this: 
weekly-reporting/
  SKILL.md
  scripts/
    build_summary.py
  references/
    reporting-guidelines.md
  assets/
    report-template.md

​
Required: SKILL.md

This is the entry point. It tells the agent what the skill does, when to use it, and how to proceed. At minimum, it should include frontmatter like this: 
---
name: weekly-reporting
description: Generate a weekly marketing summary in our standard format. Use when the user asks for weekly reporting or KPI summaries.
---
After the frontmatter, add the actual instructions in Markdown. If you are using Markifact’s Write Instructions form, you do not type this frontmatter yourself. Markifact builds it for you from the separate Name and Description inputs.

​
Optional: scripts/

Use scripts when the task requires exact logic, deterministic formatting, or repeatable data processing. Examples:
  • Data reshaping
  • Metric calculations
  • File transformations
  • Report assembly helpers

​
Optional: references/

Use this for longer docs that would make SKILL.md too heavy. Examples:
  • Internal naming conventions
  • Channel-specific rules
  • Extended examples
  • Lookup tables or structured guidance

​
Optional: assets/

Use this for static files the skill may rely on. Examples:
  • Templates
  • Boilerplate content
  • Static reference files used in outputs

​
Writing Better Skills

The best skills are narrow, concrete, and easy for the agent to activate.

​
1. Write A Specific Description

The description is the discovery surface. It should explain both:
  • What the skill does
  • When the agent should use it
Good:
Generate weekly paid media summaries with channel-by-channel highlights and action items. Use when the user asks for weekly reporting, KPI rollups, or client-ready summaries.
Weak:
Helps with reports.

​
2. Keep Skills Focused

One skill should solve one clear class of problems well. Better:
  • weekly-reporting
  • campaign-qa-checklist
  • brand-post-formatting
Worse:
  • marketing-everything

​
3. Put Precision In Scripts

If something needs to be exactly right every time, move it into a script instead of leaving it to the model. Good candidates:
  • Calculations
  • Deterministic data transforms
  • Repeated file processing steps

​
4. Keep SKILL.md Lean

Keep the core instructions concise. If the file starts turning into a large reference manual, move the detail into references/ and let the agent load that content only when needed.

​
5. Include Concrete Patterns

When useful, include:
  • Examples of the kinds of requests that should trigger the skill
  • A step-by-step workflow
  • Output expectations or formatting rules

​
System Skills Vs. Custom Skills

TypeWho provides itEditable?Typical use
System skillMarkifactNoBuilt-in reusable capability
Custom skillYou or your team through an agentYesAgent-specific process, context, or workflow
Custom skills can be inspected from the agent’s Skills page, where you can open the skill and browse its file tree.

​
Practical Rule Of Thumb

Use a skill when the agent needs reusable task-specific context. Do not use a skill when:
  • The rule belongs in the agent’s general instructions
  • The task is a one-off and does not need to be reused
  • The content adds no real logic, structure, or reusable context
If a skill is only prompt bloat, it is not helping.

AI Agents

Learn how agents work in Markifact and where skills fit into the broader agent model.

Bring Your Own Keys

Configure the model provider that powers your agents and skill usage.