# Python-Backed Skills vs Markdown Skills in Prime Agent: Architecture and Implementation > Discover Python-backed skills vs Markdown skills in Prime Agent. Learn how Python skills offer direct async calls and runtime execution, unlike static Markdown instructions. - Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) - Tags: architecture - Published: 2026-08-10 --- **Python-backed skills are executable Python packages that install into the IPython kernel for direct async calls, whereas markdown skills provide only textual instructions without runtime code execution.** Python-backed skills extend the standard Agent Skills specification in the PrimeIntellect-ai/prime-agent repository by combining documentation with installable code. While both skill types use [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) front-matter for agent prompts, Python-backed skills ship a complete Python package that binds to the kernel environment, enabling programmatic invocation and CLI integration. ## Core Architectural Differences The distinction between these skill types manifests across six key dimensions: **Package Structure** - **Markdown skills**: Contain only a [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) file and optional static assets. - **Python-backed skills**: Require [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md), [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml), and a valid Python import layout (`src//__init__.py`). **Detection Contract** - **Markdown skills**: Presence of [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) is sufficient for discovery. - **Python-backed skills**: Must satisfy the three-file contract defined in [`packages/coding-agent/skills/skill-creator/references/python-skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/references/python-skills.md): [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) + [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) + `src//__init__.py`. **Kernel Exposure** - **Markdown skills**: No direct Python callable; the model interprets textual instructions only. - **Python-backed skills**: The module installs editable into `~/.prime/agent/kernel-venv` (by default) and registers under the import name (skill name with hyphens converted to underscores), exposing `await (…)` or `await .run(…)` interfaces. **CLI Integration** - **Markdown skills**: No shell invocation capability. - **Python-backed skills**: Support shell cell invocation (`! …`) when `[project.scripts]` defines a console entry point using `rlm.skill:cli`. **Dependency Management** - **Markdown skills**: Zero runtime dependencies. - **Python-backed skills**: Declare dependencies in [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml); the kernel venv installs them automatically on first load. **Failure Modes** - **Markdown skills**: Invalid [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) results in the skill being ignored with a warning. - **Python-backed skills**: Import failures bind the name to a placeholder that raises `RuntimeError` on invocation, preserving kernel stability. ## Detection and Installation Process According to the implementation in [`packages/coding-agent/docs/skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/skills.md), Prime Agent scans skill locations and reads [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) for the model prompt. When [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) is detected, the system: 1. Validates the Python import layout (`src//__init__.py`) 2. Installs the package in editable mode into the persistent kernel virtual environment 3. Registers the module for async calls, transforming hyphens to underscores in the import name (e.g., `word-count` becomes `word_count`) ## Implementation Examples ### Minimal Python-Backed Skill Structure The `word-count` skill illustrates the required layout: ``` word-count/ ├── SKILL.md ├── pyproject.toml └── src/ └── word_count/ └── __init__.py ``` **[`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md)** provides the agent-facing documentation: ```markdown --- name: word-count description: Count word frequencies in text and return the most common words. Use when the user asks for word counts or frequency analysis. --- # Word Count Call directly from the kernel: await word_count("some text to analyze", top=3) Or from a shell cell: !word_count "some text to analyze" --top 3 ``` **[`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml)** declares the package metadata and optional CLI entry: ```toml [project] name = "word-count" version = "0.1.0" requires-python = ">=3.10" dependencies = [] [project.scripts] word_count = "rlm.skill:cli" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = ["src/word_count"] ``` **[`src/word_count/__init__.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/word_count/__init__.py)** implements the callable API: ```python from collections import Counter async def run(text: str, top: int = 5) -> str: """Count words in text and return the most common ones.""" counts = Counter(text.lower().split()) return "\n".join(f"{word}: {count}" for word, count in counts.most_common(top)) ``` ### Using Skills in a Prime Agent Session Once loaded, Python-backed skills expose multiple invocation patterns: ```python # Direct async call (module is callable via wrapper) await word_count("prime agent is awesome", top=3) # Explicit run method call await word_count.run("prime agent is awesome", top=3) # Shell-style invocation from notebook cells !word_count "prime agent is awesome" --top 3 ``` ### Markdown-Only Skill Comparison A standard markdown skill provides only instructions: ```markdown --- name: quick-note description: Append a short note to a local markdown file. --- # Quick Note Create a note in `notes.md`: echo "Your note" >> notes.md ``` The model can only follow the textual guidance; there is no `await quick_note(...)` callable or dependency management. ## Key Implementation Files | File | Purpose | |------|---------| | [`packages/coding-agent/docs/skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/skills.md) | Main skills documentation covering discovery rules and Python-backed skill architecture | | [`packages/coding-agent/skills/skill-creator/references/python-skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/references/python-skills.md) | Contract specification detailing detection requirements, `run()` conventions, and verification steps | | [`packages/coding-agent/skills/skill-creator/SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/SKILL.md) | Built-in skill description showing creation patterns for both skill types | ## Summary - **Python-backed skills** require [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md), [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml), and `src//__init__.py` to satisfy the detection contract. - Packages install into the persistent IPython kernel at `~/.prime/agent/kernel-venv` with editable mode. - Import names convert hyphens to underscores (e.g., `my-skill` → `my_skill`) for kernel registration. - Skills support both `await` calls and shell invocation via `[project.scripts]` entry points. - **Markdown skills** provide only documentation with zero runtime footprint and no callable interface. ## Frequently Asked Questions ### What file structure is required to create a Python-backed skill in Prime Agent? You must provide three components: a [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) file containing the agent prompt and front-matter, a [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) defining the package metadata and dependencies, and a Python module at `src//__init__.py` implementing the skill logic. The `import_name` is derived from the skill name with all hyphens converted to underscores, as specified in [`packages/coding-agent/skills/skill-creator/references/python-skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/references/python-skills.md). ### How does Prime Agent handle dependencies for Python-backed skills? Dependencies listed in [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) are automatically installed into the kernel virtual environment (default location: `~/.prime/agent/kernel-venv`) when the skill is first loaded. The system uses editable installs to ensure the skill code remains updatable without reinstallation. ### Can Python-backed skills be invoked from shell cells in Prime Agent? Yes, when the [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) includes a `[project.scripts]` section mapping a command name to `rlm.skill:cli`, the skill becomes available as a shell command. You can invoke it using `!` syntax from notebook cells, in addition to the standard Python `await` calls. ### What happens if a Python-backed skill fails to import correctly? If the Python import fails during skill loading, Prime Agent binds the skill name to a placeholder object that raises a `RuntimeError` when called. This design isolates the failure, allowing the IPython kernel to remain stable and other skills to function normally, unlike markdown skills which are simply skipped with a warning if their documentation is invalid.