Skills and system prompt
A skill is a Markdown file of instructions that teaches the agent how to do a specific job (for example, how to build a Word document or how to cite web sources). Skills are attached to agent profiles; the system prompt is the hidden set of instructions the agent receives before every conversation. This page explains how skills are added to that prompt, the skill file format and the skills registry. It is for administrators who manage profiles and skills and for developers who write new skills.
Two modes of skill injection
Controlled by AION_SKILL_SYSTEM_PROMPT_MODE:
index(default): in the system prompt only the name, description and tags of the profile's skills appear. The full Markdown body is not concatenated (greatly reduces tokens).full: “legacy” behavior: every profile skill is attached in its entirety after the instructions section.
The construction takes place in AgentProfile.generate_system_prompt() (src/agent_profile.py), used by get_agent() in src/main.py.
Model routing: src/runtime/system_prompt.py merges fragments from config_std/prompts/ (default.txt, gpt.txt, anthropic.txt, qwen_vllm.txt) based on provider/model id. Disable with AION_MODEL_PROMPT_FRAGMENTS=0.
Extended tool descriptions for sandbox write/edit/patch live in config_std/tool_descriptions/ (loaded via load_tool_description() when wiring MCP descriptions).
Artifact protocol (tool-first)
The curated skill artifact_protocol (config_std/skills/artifact_protocol.md, v8) is the single source for file-delivery rules. Legacy per-strategy skills (artifact_protocol_tool, artifact_protocol_xml, artifact_protocol_markdown) were removed — delivery is always via sandbox tools unless AION_ARTIFACT_STREAM_LEGACY=1.
Companion skill docx documents the docx-js workflow (skill_view → write script → sandbox_run_node_file). docx-js is the default for new documents, python-docx only a fallback. The docx and pptxgenjs Node packages are preinstalled in the Docker images (NODE_PATH, always forwarded to sandbox processes even with a custom AION_SANDBOX_ENV_ALLOWLIST); sandbox_install_npm_packages skips packages that are preinstalled or already in the session's workspace/node_modules, and a "Cannot find module" failure returns a HINT telling the agent whether to switch to require(), install the package or fall back to python-docx. Legacy .doc (Word 97–2003) is converted to .docx on the API host at upload — see Office files and legacy Word.
For multi-page PDF → Word reports with screenshots, skill long_document_protocol requires MCP pdf_evidence_crop (server ocr) instead of full-page pdftoppm. See PDF evidence images.
Skill file format
Skills are Markdown files with YAML frontmatter (python-frontmatter):
Typical fields:
name: unique slug (default: file stem).description: brief text for the index inindexmode.tags: list of strings.status: e.g.verifiedordraft.source:curated(underconfig/skills/) orgenerated(underdata/skills/generated/).version: integer; in case of slug duplicates, the highest version wins.
Directories:
config_std/skills/*.md— Templates of "curated" skills (versioned in Git).config/skills/*.md— Active skills loaded by the agent (populated fromconfig_stdor created locally).config/public_skills.yaml— (New) Configuration for integrating skills coming from external/public sources.data/skills/generated/*.md— Automatically proposed skills (distill); directory ignored by Git.
The registry is SkillRegistry in src/skill_registry.py (skill_registry singleton). Useful methods: list_summaries(), get_skill_full() / get_skill(), search(), reload().
Progressive disclosure and MCP skills_hub
With index mode, the agent must load the full text or manage its own skills via MCP tools on the skills_hub server (see config/mcp_registry.yaml and mcp_servers/skills_hub/server.py):
| Tool | Purpose |
|---|---|
skill_search | Text search on name/description/tags (limited to the skills of the active profile when AION_CURRENT_PROFILE_SLUG is set on the MCP subprocess) |
skill_view | Returns the Markdown body; for skills with a scripts/ folder, materializes the assets in the session (AION_CHAT_SESSION_ID). At the end, the AION skill assets footer appears. With AION_SKILL_VIEW_ENFORCE_PROFILE=1 (default) it is allowed only for skills listed in profile.skills (gate in mcp_servers/skills_hub/server.py + src/runtime/skill_profile_gate.py) |
skill_list | List of name + description of the skills of the active profile (if enforce active) |
sandbox_materialize_skill_scripts | (session_sandbox) Manual re-sync of skill scripts in the session |
skill_save | Creates or updates an AION skill with YAML frontmatter (saves in data/skills/generated/ for company sharing or config/skills/ for permanence) |
skill_delete | Physically deletes a skill from the filesystem and removes it from the registry |
Profile allowlist on read (AION_SKILL_VIEW_ENFORCE_PROFILE)
- Default:
1in.env.exampleandenvof theskills_hubserver inconfig_std/mcp_registry.yaml. - Effect:
skill_view/skill_listrespectskills:of the profile (AION_CURRENT_PROFILE_SLUGon the MCP subprocess). Example:db_navigation_mapcan remain inconfig/skills/as a seed file but not be readable bypostgres_metadata_assistantif removed from the profile. - Disable (dev only):
AION_SKILL_VIEW_ENFORCE_PROFILE=0. - Deploy: after updates to
mcp_servers_std/skills_hub, runpython scripts/sync_mcp_servers.py --forceand restart the backend.
Security and Write Gating (AION_SKILL_WRITE_ENABLED)
To prevent unauthorized or accidental execution of writing and removing skills by the agent, the skill_save and skill_delete tools are protected by a gating mechanism at the MCP server level:
- Configuration: The
AION_SKILL_WRITE_ENABLEDenvironment variable (default"1") must be declared specifically under theenvsection of theskills_hubserver insideconfig/mcp_registry.yaml. - Write Block: By setting
AION_SKILL_WRITE_ENABLED: "0", any attempt by the agent to invokeskill_saveorskill_deletewill fail immediately, returning a clear and clean error.
Skill Sharing at the Organization Level
Unlike the individual MCP credentials of single users, skills constitute the team's collective knowledge asset. Therefore, all skills dynamically generated via skill_save are saved in the central folder data/skills/generated/ and instantly reloaded into the agent's global registry. This allows all users in the organization to immediately benefit from the learned automations.
Coexistence between MCP Learning (Active) and Asynchronous Distillation (Passive)
Dynamic skills generated in chat coexist perfectly with the automatic background distiller (SkillDistiller):
- Active Learning (Phase S -
skills_hubMCP): The agent autonomously decides to save a skill during its turn. Gated viaAION_SKILL_WRITE_ENABLEDin themcp_registry.yamlfile. - Passive Learning (Phase B -
SkillDistiller): The server asynchronously analyzes post-turn logs to distill recurring flows without slowing down the response or consuming user tokens. Gated viaAION_SKILL_DISTILL_ENABLEDin the global.env.
Lifecycle P2: generated skills have status: draft until promotion (POST /admin/skills/{slug}/promote or button in admin-ui). skill_search excludes drafts; skill_view records metrics if AION_SKILL_VIEW_METRICS=1.
Both modules use the same SkillRegistry singleton and both write to data/skills/generated/, guaranteeing absolute consistency in real time. For an in-depth analysis of architectural trade-offs, consult the guide on Hermes Features.
Add skills_hub to the profile's mcp_servers list in config/profiles/*.yaml.
Mandatory discovery (soft)
In index mode, the system prompt reminds to invoke skill_search → skill_view before office tasks or writing files. The pipeline can add an internal turn nudge (src/runtime/skill_discovery_nudge.py) when the user message mentions documents/courses and the profile exposes skills_hub.
Remove doc_intelligence from critical_skills if the skill does not exist in the registry (phantom slug = no inlined block).
Frontmatter migration
To add frontmatter to existing flat skills:
python scripts/migrate_skills_frontmatter.py
(Requires python-frontmatter installed.)