Skills System

---
name: copywriting-sop
description: >
  Use when writing blog posts, social copy, email campaigns, or any
  client-facing long-form or short-form content. Don't use for data
  analysis, keyword research, or technical configuration tasks.
---
 
# Copywriting SOP
 
...skill instructions...

skills-library/
└── copywriting-sop/
    ├── SKILL.md               # Main instructions (loaded via load_skill)
    └── references/
        ├── examples.md        # Before/after copy examples
        └── tone-cheatsheet.md # Quick tone reference per platform

MongoDB: skills collection
{
  _id:                ObjectId,
  tenantId:           string | null,      // null = global skill
  name:               string,             // kebab-case, unique per tenantId scope
  description:        string,             // routing description — shown in manifest
  category:           string,             // see categories above
  content:            string,             // Markdown content (main SKILL.md body)
  references:         Array<{             // optional auxiliary sections
    name:   string,                       // section identifier (e.g. 'examples')
    content: string,                      // Markdown content
  }>,
  isClientContext:    boolean,            // true = this tenant's context file
  assignedAgentRoles: AgentRole[],        // which agents receive this skill in their manifest
  version:            number,             // incremented on each edit
  createdAt:          Date,
  updatedAt:          Date,
}

interface SkillManifestEntry {
  name:        string;
  description: string;
  _id:         string;
  hasRefs:     boolean;  // true if references[] is non-empty
}
 
interface ResolvedSkillSet {
  contextFile: Skill | null;          // always injected in full
  manifest:    SkillManifestEntry[];  // metadata-only; loaded on demand
}
 
async function resolveSkillsForActivity(
  tenantId: string,
  agentRole: AgentRole,
): Promise<ResolvedSkillSet> {
  // 1. Get global skills assigned to this agent role
  const globalSkills = await skillsCollection.find({
    tenantId:            null,
    assignedAgentRoles:  agentRole,
  }).toArray();
 
  // 2. Get tenant-specific overrides for this agent role
  const tenantSkills = await skillsCollection.find({
    tenantId,
    assignedAgentRoles: agentRole,
    isClientContext:    { $ne: true },
  }).toArray();
 
  // 3. Always include the client context file (full content, not manifest)
  const contextFile = await skillsCollection.findOne({
    tenantId,
    isClientContext: true,
  });
 
  // 4. Tenant skills override globals of the same category
  const skillMap = new Map(globalSkills.map(s => [s.category, s]));
  for (const skill of tenantSkills) skillMap.set(skill.category, skill);
 
  // 5. Build manifest — name + description only, no full content
  const manifest: SkillManifestEntry[] = [...skillMap.values()].map(s => ({
    name:        s.name,
    description: s.description,
    _id:         s._id.toString(),
    hasRefs:     s.references.length > 0,
  }));
 
  return { contextFile, manifest };
}

# Available Skills
 
The following skills are available for this task. Call `load_skill` with the
skill name to retrieve the full instructions for any skill that applies.
 
---
 
**copywriting-sop**
Use when writing blog posts, social copy, email campaigns, or any client-facing
long-form or short-form content. Don't use for data analysis or keyword research.
 
---
 
**blog-post-template**
Use when structuring a new blog post output. Don't use for social media formats
or short-form copy.
 
---
 
**platform-character-limits**
Use when publishing or formatting content for a specific social platform.
Load this to check character limits, image specs, and hashtag rules.

name: load_skill

description:
  Load the full instructions for a skill listed in the skills manifest. Only call
  this for skills that are directly relevant to the current task. Calling
  irrelevant skills wastes your context budget.

inputs:
  name     (string, required) — the skill name exactly as listed in the manifest
  section  (string, optional) — name of a reference section to load instead of
                                the main skill content (only if the skill has
                                hasRefs: true and you need auxiliary detail)

Agent reads _SKILLS_AVAILABLE.md
        │
        ▼
Agent determines: which skills apply to this task?
  → "I'm writing a blog post. I need copywriting-sop and blog-post-template."
  → "platform-character-limits is not relevant for a long-form blog post."
        │
        ▼
Agent calls: load_skill({ name: 'copywriting-sop' })
        │
        ▼
Tool dispatcher:
  1. Verify name is in the resolved manifest for this tenant/role
  2. Fetch full content from MongoDB by name + tenantId scope
  3. Return content string to agent
        │
        ▼
Agent incorporates skill content into working context
        │
        ▼
Agent calls: load_skill({ name: 'blog-post-template' })
        │
        ▼
Agent proceeds with task using loaded context

Agent calls: load_skill({ name: 'copywriting-sop', section: 'examples' })
→ Returns only the 'examples' reference block, not the full skill content

Activity worker picks up job
        │
        ▼
resolveSkillsForActivity(tenantId, agentRole)
  → contextFile:  full client context Markdown
  → manifest:     [{ name, description, _id, hasRefs }, ...]
        │
        ▼
Create temp directory /tmp/skills-<uuid>/
Write: client-context.md         (full content — always present)
Write: _SKILLS_AVAILABLE.md      (generated manifest — names + descriptions)
        │
        ▼
Register load_skill tool in adapter tool list
        │
        ▼
Pass tempDir to adapter
  Claude:        --add-dir /tmp/skills-<uuid>
  Codex:         symlink tempDir into CODEX_HOME/skills/ (Codex reads from skills dir automatically)
  Gemini:        symlink tempDir into ~/.gemini/skills/ (Gemini reads from skills dir automatically)
  Ollama/OpenAI: client-context.md + _SKILLS_AVAILABLE.md prepended to system prompt
                 load_skill registered as a tool
        │
        ▼
Agent runs
  → reads manifest, calls load_skill() for relevant skills
  → each load_skill call fetches from MongoDB on demand
        │
        ▼
finally: rm -rf /tmp/skills-<uuid>

skills-library/
├── copywriting-sop/
│   ├── SKILL.md
│   └── references/
│       ├── examples.md
│       └── tone-cheatsheet.md
├── blog-post-template/
│   └── SKILL.md
├── social-post-template/
│   └── SKILL.md
├── platform-character-limits/
│   ├── SKILL.md
│   └── references/
│       └── platform-specs-table.md
├── seo-research-sop/
│   ├── SKILL.md
│   └── references/
│       └── keyword-scoring-guide.md
├── social-media-sop/
│   └── SKILL.md
├── paid-ads-sop/
│   └── SKILL.md
├── data-analyst-sop/
│   └── SKILL.md
└── kpi-definitions/
    └── SKILL.md

skills/
├── src/
│   ├── resolver.ts         # resolveSkillsForActivity() — returns contextFile + manifest
│   ├── injector.ts         # createTempDir, write context file + manifest file, cleanup
│   ├── load-skill-tool.ts  # load_skill tool handler — fetches full content from MongoDB
│   ├── manifest.ts         # buildManifestFile() — renders _SKILLS_AVAILABLE.md
│   └── types.ts
└── package.json