promptex-py（alpha 原型）

promptex 的 Python SDK 最小原型。目前的能力只有一項：宣告 skill，建置成 Claude Code 的 SKILL.md 產物。

這不是什麼

本套件是早期 alpha，不是完整的 promptex。正式版的單一套件內含 SDK、核心的 預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列 工具只有 build 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、 沒有安裝與所有權登記。plugin 與 adapter 的契約面（Plugin、AdapterContext、 defineTarget 等）是介面樁：型別與簽名逐字複製正式版，方法本體一律拋錯， 存在的目的是讓第三方擴充能對本套件編譯並發布；要實際執行，工作區得覆寫成本地的 正式版 SDK。

介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被 整份取代。

安裝

pip install --pre promptex-py

需要 Python 3.10 以上。--pre 是必要的：預發布版號不會被 pip 預設選中。

用法

把宣告寫在 prompts/ 下：

# prompts/skill.py
from promptex import config, define_skill

commit_helper = define_skill(
    "commit-helper",
    "Commit 訊息協助",
    config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
    content=[
        "依 Conventional Commits 撰寫：type(scope): subject。",
        "subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。",
    ],
)

建置：

promptex build

產出 ./.claude/skills/commit-helper/SKILL.md：

---
name: commit-helper
description: 當使用者要求撰寫 commit 訊息時使用
---

依 Conventional Commits 撰寫：type(scope): subject。

subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。

命令列選項

promptex build [--src <目錄>] [--out <目錄>]

  --src <目錄>   宣告檔所在目錄，預設 prompts
  --out <目錄>   產物輸出目錄，預設當前目錄

程式化呼叫

from promptex import build, config, define_skill

define_skill("commit-helper", "Commit 訊息協助", config=config(when_to_use="..."), content="...")
written = build(".")

授權

MIT OR Apache-2.0，見 LICENSE-MIT 與 LICENSE-APACHE。