Skills as Agent Memory: A Framework for Reusable Agent Intelligence in Auctor

Version 1.0 — March 2026

Abstract

Modern AI agent systems encode their domain knowledge in two places: the model weights they ship with, and the instruction strings developers write for them. The first is frozen at training time. The second is frozen at deploy time. Neither can be refined by the operators who use the system daily.

This paper introduces a third layer — Skills — a file-based primitive for packaging reusable agent instructions, reference material, and executable scripts into discoverable, searchable, version-controlled units. We examine the Skills primitive as implemented in the Mastra AI framework, analyze how it maps onto the Auctor content engine's nine-agent architecture, and propose an adoption path that shifts Auctor's agent intelligence from static code to living, operator-editable documents.

The core claim is simple: agent instructions should be content, not code.

1. Introduction

The Problem with Inline Instructions

Auctor operates a nine-agent content pipeline spanning competitive intelligence, content creation, and publishing. Each agent carries an instructions string — a paragraph or two of natural language that tells the agent who it is, what tools it has, and how to behave.

These strings live in TypeScript source files. Changing how the editor agent evaluates factual claims requires a code change, a review, a deploy. The operator who notices the agent is too lenient on sourcing cannot fix it without involving the engineering team.

This is the same problem that plagued early web applications: content was embedded in code. The solution then was to extract content into databases and CMSes. The solution here is analogous — extract agent instructions into a structured, discoverable, file-based system that agents can load on demand.

What We Want

Operator-editable intelligence — Refine how agents think by editing markdown files, not deploying code
Composable knowledge — Share a brand voice guide across writer, editor, and strategy agents without duplication
On-demand loading — Agents pull relevant guidance when they need it, keeping system prompts lean
Searchable guidance — Agents find relevant instructions across all skills via keyword or semantic search
Version control — Pin production agents to a known-good instruction set while iterating in development

2. The Skills Primitive

Skills were introduced in @mastra/core@1.1.0 and follow the open Agent Skills specification. The design is intentionally simple.

2.1 Anatomy of a Skill

A skill is a folder. It contains one required file and up to three optional directories:

/skills/competitive-analysis/
  SKILL.md              ← Required. Instructions + metadata.
  references/           ← Optional. Supporting documentation.
    threat-scoring.md
    gap-analysis.md
  scripts/              ← Optional. Executable scripts.
    score-threats.ts
  assets/               ← Optional. Images, templates, data files.
    competitor-matrix.csv

The SKILL.md file uses YAML frontmatter for machine-readable metadata, followed by freeform markdown instructions:

---
name: competitive-analysis
description: Analyzes competitor content strategy and identifies gaps
version: 1.0.0
tags:
  - strategy
  - intelligence
---

# Competitive Analysis

You are performing competitive content analysis. Follow these steps:

1. Pull the domain summary for the target competitor
2. Score threats using the rubric in references/threat-scoring.md
3. Identify coverage gaps against our content graph
4. Rank opportunities by estimated traffic impact

The frontmatter is intentionally minimal — name, description, version, tags. Everything else is natural language. The agent reads it like documentation because that is exactly what it is.

2.2 How Agents Discover Skills

When a Workspace has skills configured, Mastra injects three tools into every agent connected to that workspace:

Tool	Behavior
`skill`	Loads a skill's full `SKILL.md` content into the agent's context. The agent calls this whenever it needs guidance.
`skill_read`	Reads a specific file from a skill's `references/`, `scripts/`, or `assets/` directory.
`skill_search`	Searches across all skill content using BM25 keyword search or vector similarity. Returns relevant fragments.

Available skills are listed in the agent's system message so it knows what exists. The agent decides when to load a skill based on the task at hand.

2.3 Stateless by Design

There is no "activate" or "deactivate" state. An agent loads a skill's instructions via the skill tool, receives the content in the tool result, and uses it to guide its behavior. If the instructions later fall out of the context window due to conversation length or compaction, the agent simply calls skill again to reload them.

This is a deliberate design choice. Stateless loading means:

No activation state to synchronize across agents
No risk of stale cached instructions
Agents can load multiple skills simultaneously
Skills can be updated on disk between agent turns

2.4 Search and Indexing

Skills integrate with the workspace's search infrastructure. When BM25 or vector search is enabled, skill content is automatically indexed alongside other workspace files. An agent can call skill_search("how to score competitor threats") and receive matching fragments from across all skills — even if it doesn't know which specific skill contains the answer.

This is particularly powerful for agents handling novel requests that span multiple skills. The agent doesn't need to know the skill taxonomy; it searches by intent.

2.5 Configuration

Skills are enabled by adding a skills property to the Workspace constructor:

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['/skills'],
  bm25: true,
})

The configuration supports static paths, multiple directories, glob patterns for nested discovery, and dynamic path functions that can vary by context:

// Multiple skill sources
skills: ['/skills', '/team-skills', '/client-skills']

// Glob-based discovery
skills: ['./**/skills']

// Dynamic based on context
skills: (context) => {
  const paths = ['/skills']
  if (context.user?.role === 'strategist') {
    paths.push('/strategy-skills')
  }
  return paths
}

2.6 Versioned Skills for Production

For production environments, Mastra provides VersionedSkillSource — a mechanism that serves published skill versions from a content-addressable blob store:

import { VersionedSkillSource } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['/skills'],
  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
})

This decouples skill content from the live filesystem. Production agents read from an immutable snapshot while development agents read from the working directory. The versionTree is a manifest mapping file paths to content-addressed blob hashes, ensuring reproducibility.

3. Auctor Today

3.1 Architecture Overview

Auctor is an operator tooling system for content strategy, creation, and publishing. Its AI layer is built on the Mastra framework and consists of:

9 Content Engine agents organized into three pipeline layers
3 Harness orchestrator agents that coordinate multi-agent workflows
5 Harness subagents that execute specialized tasks
42 tools spanning research, planning, content, and publishing
3 workflows (strategy planning, brief generation, draft production)
1 Workspace with BM25 search over library, content, and strategy files

3.2 The Three Pipeline Layers

┌─────────────────────────────────────────────────┐
│  STRATEGY (Indigo)                              │
│  competitive-intelligence → search-landscape    │
│  → content-strategy                             │
├─────────────────────────────────────────────────┤
│  CONTENT (Amber)                                │
│  content-brief → writer → editor                │
├─────────────────────────────────────────────────┤
│  PRODUCTION (Emerald)                           │
│  final-cleanup → publishing → seo-autofix       │
└─────────────────────────────────────────────────┘

Each agent has a fixed set of tools and an inline instruction string. The harness provides an interactive layer with three modes (Strategy, Create, Ops) that map to these pipeline layers, each with an orchestrator that delegates to subagents.

3.3 How Instructions Work Today

Agent instructions are TypeScript string literals in source code. For example, the writer subagent:

{
  id: 'writer',
  instructions:
    'You are the primary draft writer for Consul (consul.ai). Follow the '
    + 'brief exactly, write in a confident operator voice, and mark image '
    + 'opportunities as [IMAGE: description]. Do not invent unsupported '
    + 'claims. Use extractions and graph data to ground every assertion. '
    + 'Target a high-trust B2B SaaS audience of CEOs and founders.',
}

This is the entirety of the writer's identity and behavioral guidance. It works, but it has three structural problems:

Monolithic — Voice guidance, structural rules, audience definition, and sourcing policy are compressed into one paragraph. There's no way for the agent to selectively load "just the voice rules" for a quick edit pass.
Static — Changing "confident operator voice" to something more specific requires a code change. The operator who writes content daily has no mechanism to refine these instructions based on what they observe.
Duplicated or absent — The voice definition exists in the writer instructions but not the editor's. The editor should enforce the same voice but has no reference to it. Adding it means maintaining the same text in two places.

3.4 The Workspace Gap

Auctor already has a Mastra Workspace with BM25 search enabled. It indexes /library/**, /content/**, and /strategy/**. Agents can search and read workspace files.

But the workspace has no skills property configured. The skill, skill_read, and skill_search tools are not available to agents. The workspace is a file system with search — not yet an instruction system.

4. Proposed Skill Architecture

4.1 Skill Taxonomy

We propose nine skills mapped to Auctor's three pipeline layers. Each skill encapsulates a distinct competency that one or more agents need:

Strategy Layer

Skill	Description	Consumers
`competitive-analysis`	How to analyze competitor pages, score threats, identify content gaps, and assess domain authority trends	competitive-intelligence, strategy orchestrator
`serp-interpretation`	How to read SERP features (featured snippets, AI overviews, PAA), classify intent, and assess ranking opportunity	search-landscape, strategy orchestrator
`content-planning`	How to prioritize topics, balance the content calendar, define KPIs, and evaluate content-market fit	content-strategy, strategy orchestrator

Content Layer

Skill	Description	Consumers
`brief-writing`	How to structure content briefs: angle selection, outline architecture, keyword mapping, source requirements, and competitive positioning	content-brief, create orchestrator
`consul-voice`	Consul's brand voice, tone, audience profile, terminology, and writing rules. The single source of truth for how Consul content should sound.	writer, editor, content-brief, create orchestrator
`draft-structure`	Post anatomy: hooks, section patterns, CTA placement, internal linking strategy, image placement, and length targets by content type	writer, editor, create orchestrator

Production Layer

Skill	Description	Consumers
`seo-checklist`	Pre-publish SEO validation: title/meta requirements, internal link minimums, schema markup, image alt text, heading hierarchy, and canonical URL rules	final-cleanup, seo-autofix, ops orchestrator
`cms-publishing`	CMS adapter formatting: field mappings, metadata payload structure, indexing API protocol, and staging vs. production publish rules	publishing, ops orchestrator
`post-publish-ops`	Post-publish monitoring: what to check (indexing status, ranking movement, error rates), when to check it, and escalation criteria	seo-autofix, ops orchestrator

The key insight is that skills are not one-to-one with agents. The consul-voice skill is loaded by three different agents, each using it for a different purpose:

consul-voice
  ├── writer     → uses it to set tone while drafting
  ├── editor     → uses it to evaluate tone consistency
  └── content-brief → uses it to set voice expectations in the brief

Today, this voice guidance either lives in one agent's instructions (and the others don't have it) or is duplicated across multiple instruction strings (and drifts over time). Skills solve this with a single file that multiple agents load on demand.

4.3 Filesystem Layout

Under the workspace root (AUCTOR_WORKSPACE_ROOT):

/skills/
  /competitive-analysis/
    SKILL.md
    /references/
      threat-scoring-rubric.md
      gap-analysis-template.md
      domain-authority-benchmarks.md
  /serp-interpretation/
    SKILL.md
    /references/
      serp-feature-taxonomy.md
      intent-classification-guide.md
      ai-overview-analysis.md
  /content-planning/
    SKILL.md
    /references/
      prioritization-framework.md
      kpi-definitions.md
      calendar-balancing-rules.md
  /brief-writing/
    SKILL.md
    /references/
      brief-template.md
      outline-patterns.md
      angle-selection-criteria.md
  /consul-voice/
    SKILL.md
    /references/
      voice-guide.md
      terminology-glossary.md
      audience-profile.md
      tone-examples.md
  /draft-structure/
    SKILL.md
    /references/
      post-anatomy.md
      hook-patterns.md
      internal-link-strategy.md
      content-type-specs.md
  /seo-checklist/
    SKILL.md
    /references/
      seo-requirements.md
      schema-templates.md
      heading-hierarchy-rules.md
  /cms-publishing/
    SKILL.md
    /references/
      cms-field-map.md
      metadata-payload-spec.md
      indexing-protocol.md
  /post-publish-ops/
    SKILL.md
    /references/
      monitoring-checklist.md
      escalation-criteria.md
      ranking-watch-schedule.md

4.4 Instruction Evolution

Agent instructions transform from monolithic behavioral descriptions to lightweight orchestration directives. The writer subagent's instructions evolve from:

Before (inline everything):

You are the primary draft writer for Consul (consul.ai). Follow the brief
exactly, write in a confident operator voice, and mark image opportunities
as [IMAGE: description]. Do not invent unsupported claims. Use extractions
and graph data to ground every assertion. Target a high-trust B2B SaaS
audience of CEOs and founders.

After (orchestration + skills):

You are the primary draft writer for Consul. For every draft:

Load the consul-voice skill for tone, audience, and terminology
Load the draft-structure skill for post anatomy and section patterns
Load the approved brief via loadApprovedBrief
Ground every assertion in extractions and graph data
Mark image opportunities as [IMAGE: description]

If you're unsure about voice or structure, search skills before guessing.

The detailed "how" — what "confident operator voice" means, what hook patterns to use, how to handle internal links — moves into skill reference documents where it can be expanded, refined, and versioned independently.

5. Integration Design

5.1 The One-Line Change

Auctor's workspace configuration requires a single addition:

// frontend/src/mastra/workspace.ts

return new Workspace({
  id: `auctor-ws-${opts.siteKey}`,
  name: `Auctor Workspace (${opts.siteKey})`,
  filesystem: new LocalFilesystem({
    basePath: workspaceRoot,
    contained: true,
    readOnly,
  }),
  skills: ['/skills'],          // ← This is the only new line
  bm25: true,                   // Already enabled
  autoIndexPaths: ['/library/**', '/content/**', '/strategy/**'],
  tools: {
    enabled: true,
    requireApproval: !readOnly,
  },
})

Because BM25 is already enabled, skill content is automatically indexed. The skill_search tool works immediately.

5.2 Harness Inheritance

The harness already receives its workspace via a factory function:

// frontend/src/mastra/harness.ts
workspace: () => createAuctorWorkspace({ siteKey: 'consul' }),

Once createAuctorWorkspace includes skills, every harness subagent — explore, research, writer, editor, validator — automatically gains access to skill, skill_read, and skill_search. No changes to the harness configuration are needed.

The three orchestrator agents (strategy, create, ops) also inherit skills through the workspace, meaning they can load skill instructions before deciding which subagent to delegate to.

5.3 On-Demand Loading Pattern

Skills are loaded contextually, not preloaded. A typical interaction:

Operator: "Write a draft for the approved brief on API gateway comparison"

Create Orchestrator:
  1. Calls skill("consul-voice") → loads voice/tone/audience guidance
  2. Calls skill("draft-structure") → loads post anatomy for "comparison" type
  3. Spawns writer subagent with these skill instructions in context

Writer subagent:
  1. Calls loadApprovedBrief → gets the brief
  2. Already has voice + structure from orchestrator context
  3. Calls skill_read("draft-structure", "references/content-type-specs.md")
     → loads comparison-specific structural guidance
  4. Writes the draft

If the conversation runs long and skill instructions are compacted out, any agent can call skill again to reload — no state management required.

5.4 Search-Driven Discovery

An operator might ask something that spans skills:

Operator: "How should we handle competitor mentions in our content?"

Strategy Orchestrator:
  1. Calls skill_search("competitor mentions content policy")
  2. Gets fragments from:
     - consul-voice/references/tone-examples.md (how to reference competitors)
     - competitive-analysis/SKILL.md (competitive positioning section)
     - draft-structure/references/hook-patterns.md (comparison hooks)
  3. Synthesizes guidance from multiple skills

The agent doesn't need to know the skill taxonomy. BM25 search finds relevant content across all skills.

6. Migration Path

Phase 1: Foundation

Goal: Wire up skills infrastructure and create seed skills with immediate value.

Add skills: ['/skills'] to createAuctorWorkspace
Create three seed skills from the highest-value instruction content:
- consul-voice — Extract and expand voice guidance from writer/editor instructions
- seo-checklist — Extract and expand from final-cleanup/seo-autofix instructions
- brief-writing — Extract and expand from content-brief agent instructions
Verify agents can call skill, skill_read, and skill_search

Validation: An agent in the harness can load consul-voice and reference it while drafting.

Phase 2: Extraction

Goal: Migrate detailed guidance from inline instructions to skills.

Create remaining six skills with full reference documents
Refactor agent instruction strings from behavioral descriptions to orchestration directives
Each agent's instructions become: "here's your role, here are the skills to load, here's when to search"
Test that agents produce equivalent or better output with skill-based instructions

Validation: Side-by-side comparison of agent outputs before and after instruction refactoring.

Phase 3: Operator Iteration

Goal: Enable operators to refine agent behavior without engineering involvement.

Document the skill file format for operators
Expose skill files in the agent workspace pane (already a file browser)
Operators edit skill content directly — voice tweaks, checklist additions, template updates
Changes take effect on the next agent turn (no deploy)

Validation: An operator modifies consul-voice/references/terminology-glossary.md and the writer agent uses the updated terminology in its next draft.

Phase 4: Production Versioning

Goal: Pin production agents to tested skill versions.

Implement VersionedSkillSource for production deployments
Publish skill snapshots as content-addressed blobs
Development reads from filesystem, production reads from versioned source
Skill changes go through a review/publish cycle before reaching production agents

Validation: Production agents use a pinned skill version that doesn't change when filesystem skills are edited.

7. Conclusion

Auctor's agents are effective but rigid. Their intelligence is encoded in TypeScript string literals that only engineers can modify and only deploys can deliver. The Skills primitive offers a clean extraction path: move the detailed "how" into structured, searchable, version-controlled markdown files while keeping the "what" and "when" in agent instructions.

The integration cost is minimal — one line of workspace configuration, plus the work of writing skill content. The return is an agent system whose knowledge layer can be refined by the people who use it, shared across agents without duplication, searched by intent rather than by name, and versioned independently from the application code.

Agent instructions should be content, not code. Skills make that possible.

Appendix A: Skill Specification Reference

SKILL.md Frontmatter

---
name: string          # Unique skill identifier
description: string   # One-line description (used for discovery)
version: string       # Semantic version
tags:                 # Discovery tags
  - string
---

Agent Skill Tools

Tool	Parameters	Returns
`skill(name)`	Skill name	Full SKILL.md content
`skill_read(name, path)`	Skill name + relative file path	File content from references/scripts/assets
`skill_search(query)`	Search query string	Matching fragments across all skills

Workspace Configuration

interface WorkspaceSkillsConfig {
  skills: string[] | ((context: SkillsContext) => string[] | Promise<string[]>)
  skillSource?: SkillSource       // Custom source (e.g., VersionedSkillSource)
  bm25?: boolean | BM25Config     // Enable keyword search
  vectorStore?: VectorStore        // Enable semantic search
  embedder?: EmbedderFunction      // For vector embeddings
}

Appendix B: Auctor Agent-to-Skill Mapping

Agent                      Skills Used
─────────────────────────  ──────────────────────────────────
competitive-intelligence   competitive-analysis
search-landscape           serp-interpretation
content-strategy           content-planning, competitive-analysis
content-brief              brief-writing, consul-voice
writer                     consul-voice, draft-structure
editor                     consul-voice, draft-structure, seo-checklist
final-cleanup              seo-checklist
publishing                 cms-publishing
seo-autofix                seo-checklist, post-publish-ops

Orchestrator               Skills Used
─────────────────────────  ──────────────────────────────────
strategy-orchestrator      competitive-analysis, serp-interpretation, content-planning
create-orchestrator        brief-writing, consul-voice, draft-structure
ops-orchestrator           seo-checklist, cms-publishing, post-publish-ops