promptex-py

Declare prompt resources in Python, compile them into whatever your AI coding tool expects on disk.

Skills, rules, agents, hooks, MCP servers and permissions are ordinary files in a directory tree, and every tool wants that tree laid out its own way. This package lets you declare each resource once and project the result onto a target platform. It ships the Python SDK, a precompiled native extension bound to the shared core, and the promptex command line tool.

Install

pip install promptex-py

Requires Python 3.10 or newer. Wheels carry the native extension, so there is no Rust toolchain to install.

Minimal example

Declarations live in a prompts/ directory. Anything you define_* at module scope is registered when the file is evaluated.

# my_project/prompts/review.py
from promptex import define_skill

define_skill(
    id="code-review",
    name="Code Review",
    description="Reviews a pull request for correctness and readability",
    config={"whenToUse": "Reviewing a pull request"},
    content="Check correctness first, then readability.",
)

Point the command line tool at the directory that contains prompts/:

$ promptex build --install my_project --out my_project --platform claude
✓ Metadata written (graph + content)
  wrote .claude/skills/code-review/SKILL.md
Install report (claude)
  Projected artifacts, 1: .claude/skills/code-review/SKILL.md

Which writes:

my_project/.claude/skills/code-review/SKILL.md

---
name: code-review
description: Reviews a pull request for correctness and readability
when_to_use: Reviewing a pull request
---

Check correctness first, then readability.

Switch --platform codex and the same declaration lands in Codex's layout instead.

Commands

Common flags: --out <install root> (single-directory mode), --platform <name> (manifest only), --unit <unit name>, --json, --locale <tag>.

What you can declare

define_skill, define_rule, define_agent, define_instruction, define_resource, define_hook, define_mcp, define_permission, define_asset, define_dir.

Each define_* takes either keyword arguments or one spec object from the promptex.kinds module (SkillDef, RuleDef, AgentDef, InstructionDef, ResourceDef, HookDef, McpDef, PermissionDef, AssetDef, DirDef). The two forms produce byte-identical intermediate representations. Spec objects are for shared packages: a pure function returns the spec, and each unit calls define_rule(rule_def(...)) in its own source file, so the node's recorded source location is the caller's line, not the package's.

from promptex import RuleDef, define_rule

def lint_rule_def(spec) -> RuleDef:
    return RuleDef(id=spec.id, name=spec.name, content=spec.statement)

define_rule(lint_rule_def(spec))

Per-platform native settings are not declared in your sources: they belong to the target, so you write them as claude(settings={…}) in promptex.config.py. Keys pass through verbatim into that platform's own settings file and the framework keeps no allowlist.

Larger projects add a promptex.config.py with define_config to split the tree into units, and register third-party platforms with define_target.

Notes

The SDK's evaluation path depends on nothing outside the standard library: writing and evaluating declarations never touches the native extension. The extension is loaded only once work moves past evaluation, which is also why the test suite runs with no build step.

Everything past evaluation — projection, install, registry, graph, diagnostics — happens in a shared Rust core called in-process, not as a subprocess. The TypeScript and Rust packages call the same core, so identical declarations produce byte-identical output across all three.

Links

• Source and issues: https://github.com/promptex-ai/promptex
• Architecture notes: https://github.com/promptex-ai/promptex/blob/main/docs/architecture.md

License

Dual-licensed under either of MIT or Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.