packages coding agent skills

Skills

Active contributors: Mario Zechner, kt, Armin Ronacher

Purpose

Skills are self-contained capability packages Prime Agent loads on demand. A skill carries specialized workflows, setup instructions, helper scripts, and reference material for a specific task. Prime Agent implements the Agent Skills standard (see packages/coding-agent/docs/skills.md) and extends it with Python-backed skills: a superset that installs an importable Python package into the persistent IPython kernel. Only a skill's name and description are placed in the system prompt; the full file loads on demand, so skills are a progressive-disclosure mechanism for extending the model without growing the always-in-context prompt.

The core loader lives in packages/coding-agent/src/core/skills.ts. Parsing of <skill> blocks from user messages lives in packages/coding-agent/src/core/skill-blocks.ts. The DefaultResourceLoader in packages/coding-agent/src/core/resource-loader.ts coordinates skill discovery with extensions, prompt templates, and themes, and feeds skills into system-prompt construction.

Directory layout

packages/coding-agent/
├── src/core/skills.ts            # Skill type, discovery, validation, prompt formatting
├── src/core/skill-blocks.ts      # <skill name location> block parsing
├── src/core/resource-loader.ts   # Loads skills with extensions/prompts/themes
└── skills/                       # Built-in skills shipped with the package
    ├── agent-message/            # Send text to parent/siblings/children via daemon
    ├── agent-observe/            # Read-only family status and message previews
    ├── attach-image/             # Load an on-disk image into model context
    ├── compact/                  # Kernel-side interface to conversation compaction
    ├── edit/                     # Replace one exact string in an existing file
    ├── goal/                     # Kernel-side interface to the thread goal
    ├── linear/                   # Linear MCP server access from IPython
    ├── notion/                   # Notion MCP server access from IPython
    ├── prime-intellect/          # Prime CLI products and workflows
    ├── refine/                   # Trigger continual harness refinement from IPython
    ├── rlm-heartbeat/            # Manage agent-owned RLM heartbeats from IPython
    ├── skill-creator/            # Teach the agent to create new skills
    └── websearch/                # Google search via the Serper API

A single skill on disk is a directory containing a required SKILL.md (YAML frontmatter plus markdown instructions) with optional freeform scripts, references, and assets. A Python-backed skill adds pyproject.toml and a src/<import_name>/__init__.py package.

Key abstractions

Type	Path	Description
Skill	packages/coding-agent/src/core/skills.ts	A discovered skill; union of MarkdownSkill and PythonSkill.
MarkdownSkill	packages/coding-agent/src/core/skills.ts	Instruction-only skill rooted at a SKILL.md.
PythonSkill	packages/coding-agent/src/core/skills.ts	Markdown skill plus a Python package metadata (importName, packagePath, pyprojectPath).
SkillPythonMetadata	packages/coding-agent/src/core/skills.ts	The importable Python identity for a Python-backed skill.
SkillFrontmatter	packages/coding-agent/src/core/skills.ts	Parsed YAML frontmatter, including name, description, disable-model-invocation.
LoadSkillsResult	packages/coding-agent/src/core/skills.ts	Skills plus validation diagnostics.
ParsedSkillBlock	packages/coding-agent/src/core/skill-blocks.ts	A parsed <skill name location> block from a user message.
ResourceLoader	packages/coding-agent/src/core/resource-loader.ts	Loads skills, extensions, prompts, themes, and context files together.
DefaultResourceLoader	packages/coding-agent/src/core/resource-loader.ts	Concrete loader; resolves package, project, and CLI resource paths.

How it works

flowchart TD
    dirs["User / project / package skill dirs + built-in skills dir"]
    loader["loadSkills / DefaultResourceLoader.reload"]
    meta["name + description + python_import extracted"]
    prompt["formatSkillsForPrompt -> XML into system prompt"]
    kernel["persistent IPython kernel"]
    invoke["/skill:name or model-driven ipython load"]
    block["parseSkillBlock"]

    dirs --> loader
    loader --> meta
    meta --> prompt
    prompt --> kernel
    kernel --> invoke
    invoke --> block
    block --> full["full SKILL.md instructions executed"]

Loading

Discovery follows these rules in packages/coding-agent/src/core/skills.ts:

• loadSkillsFromDir treats a directory containing SKILL.md as a skill root and does not recurse further; otherwise it loads direct .md children in the root and recurses into subdirectories looking for SKILL.md.
• loadSkills merges sources into one name-keyed map, deduplicates real paths via symlink canonicalization, and emits collision and shared-python-import diagnostics.
• Name validation enforces the spec: lowercase a-z 0-9 -, no leading or trailing hyphen, no consecutive hyphens, max 64 chars. A missing description prevents loading; other violations warn but still load.
• detectPythonSkill marks a skill Python-backed when pyproject.toml exists and src/<import_name>/__init__.py is present, where import_name is the skill name with hyphens converted to underscores.

formatSkillsForPrompt renders visible skills as <available_skills> XML with name, type, python_import, description, and location. Skills with disable-model-invocation: true are excluded from the prompt and reachable only via explicit /skill:name. buildSystemPrompt in packages/coding-agent/src/core/system-prompt.ts calls this and appends the section only when the model has a file-access tool (ipython or bash).

Loading and installation

Skills load from several locations with ascending precedence (user before project, explicit paths before built-ins). The DefaultResourceLoader.reload() in packages/coding-agent/src/core/resource-loader.ts resolves paths through DefaultPackageManager and the settings manager, then passes explicit paths to loadSkills with includeDefaults: false. The canonical loadSkills defaults (when called directly) scan the global ~/.prime/agent/skillsand the project.prime/agent/skills` under the working directory.

• Personal (global) skills: ~/.prime/agent/skills/ and ~/.agents/skills/.
• Project skills: .prime/agent/skills/ and .agents/skills/ in cwd and ancestor directories.
• Packages: skills/ directories or pi.skills entries in package.json, installed via prime-agent package install.
• Settings: the skills array in settings.json, each entry a file or directory.
• CLI: --skill <path>, repeatable and additive even with --no-skills.
• Built-in: packages/coding-agent/skills/ (lowest precedence), controlled by enableBuiltinSkills and per-skill bundledSkills settings.

Python-backed skills are installed editable into the kernel venv during kernel setup (default ~/.prime/agent/kernel-venv, override with PRIME_AGENT_KERNEL_VENV). A changed pyproject.toml triggers a kernel-venv rebuild. With a custom PRIME_AGENT_KERNEL_PYTHON, no packages are installed and the Python must already provide ipykernel, prime-agent-runtime, and the default runtime packages.

Slash commands and importable packages

Every skill registers as a /skill:name command (for example /skill:websearch, /skill:pdf-tools extract). Arguments after the command are appended to the skill content as User: <args>. The interactive mode expands /skill:name into a <skill name location> block using parseSkillBlock in packages/coding-agent/src/core/skill-blocks.ts; skill command support is toggled by enableSkillCommands in settings. Use /reload to rediscover new or edited skill metadata, and start a fresh session after adding a Python-backed skill so kernel setup installs and imports the package.

A Python-backed skill is also directly callable in the IPython kernel by import name:

print(await websearch("latest Prime Agent release"))

If the module defines run(), it is wrapped as an async callable (await web_search.run("query")). A skill may also declare a console script in pyproject.toml whose name matches the import name, exposing a shell command that the rlm.skill:cli helper wires to the Python run function.

The skill creator skill

packages/coding-agent/skills/skill-creator/SKILL.md teaches the agent to create new skills: markdown skill layout, frontmatter rules, placement and precedence, and the full Python-backed contract (package layout, the run() convention, optional CLI, kernel-venv behavior) with a working template in references/python-skills.md. Invoke it with /skill:skill-creator <request> or ask in plain language, telling the agent the scope (project .prime/agent/skills/<name>/ versus personal ~/.prime/agent/skills/<name>/), the kind (markdown versus Python-backed), and the intended call contract. The agent writes SKILL.md in both cases, plus pyproject.toml and src/<import_name>/__init__.py for a Python skill, and verifies the import in the kernel.

Integration points

• System prompt construction (packages/coding-agent/src/core/system-prompt.ts) reads skill metadata through formatSkillsForPrompt and getPythonSkillRuntimeInfo.
• Resource loading (packages/coding-agent/src/core/resource-loader.ts) resolves skill paths, applies settings and CLI overrides, and attaches SourceInfo for reporting.
• Skill command expansion in the interactive mode builds <skill> blocks from parseSkillBlock.
• Python-backed skills surface as imports in the kernel, installed by the kernel manager; the kernel-side behavior is documented under the rlm package in the runtime (see the rlm package page).
• The continual harness refinement flow creates and updates skill entries through /refine (see the refinement page); those entries are routing hints, separate from installing real packages via skill-creator.

Entry points for modification

• To change discovery or validation rules, edit packages/coding-agent/src/core/skills.ts (loadSkills, loadSkillsFromDir, validateName, validateDescription).
• To change how skills appear in the prompt, edit formatSkillsForPrompt in packages/coding-agent/src/core/skills.ts.
• To add a built-in skill, add a directory under packages/coding-agent/skills/ with a valid SKILL.md.
• To change how skill blocks are parsed from messages, edit packages/coding-agent/src/core/skill-blocks.ts.

Key source files

File	Role
packages/coding-agent/src/core/skills.ts	Skill type, discovery, validation, prompt formatting.
packages/coding-agent/src/core/skill-blocks.ts	<skill> block parsing from user messages.
packages/coding-agent/src/core/resource-loader.ts	Loads skills with extensions, prompts, themes, and context files.
packages/coding-agent/src/core/system-prompt.ts	Injects skill metadata and the continual harness overview into the system prompt.
packages/coding-agent/skills/	Built-in markdown and Python-backed skills.

Related pages

• Package overview, SDK surface for the coding-agent package
• Session runtime, AgentSession lifecycle and how resources are bound per session
• Slash commands, how /skill:name and /reload surface
• RLM runtime, the IPython programming model that executes Python-backed skills
• rlm package, the Python IPython kernel shim
• Patterns and conventions, repo rules