Skip to content

Manage Skills

Skills are folders of task instructions and helper scripts that the model reads on demand when a request calls for them, such as building a Word document, auditing an Excel workbook, or designing a poster. All chats and models share the same skill folders.

How skills reach the model

  1. The first user message of each chat includes a compact <available_skills> index with one line per active skill (its name and when to use it). Because the index only changes when skills or tier permissions change, it stays inside the provider's prompt cache across turns.
  2. When a request matches a skill, the model calls read_skill to read SKILL.md and any reference files it links to.
  3. When Python code in code_interpreter references /mnt/skills/<name>, that skill's folder is mounted read-only in the sandbox for that run. Helper scripts can be imported after adding /mnt/skills/<name>/scripts to sys.path, and their allowlisted package dependencies load automatically. Both code execution and the Skills tier permission are required for sandbox mounts.

Skill helpers run inside the standard Python sandbox with outbound networking disabled by default.

Built-in skills

Skill Use
data-analysis Load, profile, clean, and analyze uploaded CSV, Excel, or JSON data
docx Create, edit, and inspect Word documents
event-planning Plan events ranging from a dinner party to a wedding
financial-calculator Loans, savings, retirement, rent-versus-buy, and other financial math
gif-creator Build small animated GIFs
learn Guided tutoring, practice exercises, quizzes, flashcards, and study plans
pdf Read, split, merge, fill, stamp, and create PDFs
poster-design Create posters, flyers, cards, and generative art as PNG or PDF
pptx Create and edit PowerPoint slide decks
shopping-research Compare products and offers before buying
work-updates Status reports, newsletters, incident notes, and announcements
writing-coauthor Co-write longer documents step by step
xlsx Build, edit, and audit Excel workbooks

If a skill requires a tool or sandbox package that is disabled on the server (or unavailable in the active chat or sub-agent), it is omitted from both <available_skills> and read_skill's name enum, and the admin page shows what is missing. When no skills are usable or skills are switched off in Admin, both <available_skills> and the read_skill tool schema are omitted.

Switch skills on or off

  • Admin page: open Models and scroll to Skills. The top toggle turns all skills on or off, and individual rows toggle single skills. Changes take effect on the next request without restarting the server.
  • Server config: SKILLS_ENABLED=false disables all skills and removes the read_skill tool at startup; SKILLS_DENYLIST hides specific skills by name.
  • Tiers: the Skills feature on the Tiers admin page controls whether users in that tier can use read_skill and /mnt/skills/ mounts.
  • If you customize TOOLS_ALLOWLIST, keep read_skill in the list.

See Configuration for the environment settings.

Add a custom skill

Built-in skills live in src/numi_chat/skills/<name>/. Operators can add instance-specific skills without modifying the repository by placing a folder under state/skills/<name>/ (or the directory set in SKILLS_PRIVATE_DIR) and restarting Numi. A private skill with the same name as a built-in skill replaces it.

state/skills/meal-prep/
├── SKILL.md            required
├── reference/*.md      optional, read on demand via read_skill
└── scripts/*.py        optional Python helpers for code_interpreter

SKILL.md starts with single-line YAML frontmatter:

---
name: meal-prep
description: Plan a week of meals with a shopping list. Use when the user asks for meal plans or batch cooking.
requires: code_interpreter
packages: pandas
---

# Meal prep

Instructions for the model...
Field Rule
name Matches the folder name: 1 to 64 lowercase letters, digits, and hyphens, starting with a letter or digit
description Single line, up to 300 characters. State what the skill does and when to use it
requires Optional comma-separated tool names required by the skill
packages Optional comma-separated sandbox packages (each must be in TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST)

Keep SKILL.md concise and put longer reference material in reference/*.md. read_skill reads text files up to 200,000 bytes; binary assets and helper scripts are accessed from code_interpreter.

Document styling defaults

Unless the user asks for a specific palette or typeface, the built-in office and PDF helpers use a clean default style: Arial (or Helvetica in PDFs), dark headings, and Numi blue accents for rules, table headers, and charts. When the user specifies their own colors or fonts, the helpers use those while keeping body and heading text legible. Uploaded files keep their existing styling when edited.

Security and sharing notes

  • Private skills are available to all accounts whose tier grants Skills. Never place secrets or credentials inside skill files, as their text is sent to the active model provider when read.
  • Symlinks that point outside the skill directory are rejected by both read_skill and sandbox mounting.
  • Public share links omit read_skill calls and raw skill text, while still showing the assistant's final reply and any generated files referenced in the shared chat.