promptex-py 0.0.0__tar.gz

promptex_py-0.0.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.egg-info/
+tmp/

promptex_py-0.0.0/LICENSE-APACHE

@@ -0,0 +1,204 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing
+      lists, source code control systems, and issue tracking systems that
+      are managed by, or on behalf of, the Licensor for the purpose of
+      discussing and improving the Work, but excluding communication that
+      is conspicuously marked or otherwise designated in writing by the
+      copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE
+      file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 promptex-ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

promptex_py-0.0.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 promptex-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptex_py-0.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: promptex-py
+Version: 0.0.0
+Summary: promptex 的 Python SDK 最小原型（alpha）：宣告 skill 並投影成 SKILL.md，並提供 plugin 與 adapter 契約的介面樁（只有型別與簽名，沒有實作）
+Project-URL: Homepage, https://github.com/promptex-ai/promptex
+Project-URL: Repository, https://github.com/promptex-ai/promptex
+Project-URL: Issues, https://github.com/promptex-ai/promptex/issues
+Author: promptex-ai
+License: MIT OR Apache-2.0
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Keywords: agent,ai,claude,codegen,llm,prompt,prompt-engineering,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# promptex-py（alpha 原型）
+
+promptex 的 Python SDK **最小原型**。目前的能力只有一項：宣告 skill，建置成
+Claude Code 的 `SKILL.md` 產物。
+
+## 這不是什麼
+
+本套件是早期 alpha，**不是**完整的 promptex。正式版的單一套件內含 SDK、核心的
+預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列
+工具只有 `build` 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、
+沒有安裝與所有權登記。plugin 與 adapter 的契約面（`Plugin`、`AdapterContext`、
+`defineTarget` 等）是**介面樁**：型別與簽名逐字複製正式版，方法本體一律拋錯，
+存在的目的是讓第三方擴充能對本套件編譯並發布；要實際執行，工作區得覆寫成本地的
+正式版 SDK。
+
+介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被
+整份取代。
+
+## 安裝
+
+```bash
+pip install --pre promptex-py
+```
+
+需要 Python 3.10 以上。`--pre` 是必要的：預發布版號不會被 pip 預設選中。
+
+## 用法
+
+把宣告寫在 `prompts/` 下：
+
+```python
+# 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 說明變更動機而非變更內容。",
+    ],
+)
+```
+
+建置：
+
+```bash
+promptex build
+```
+
+產出 `./.claude/skills/commit-helper/SKILL.md`：
+
+```text
+---
+name: commit-helper
+description: 當使用者要求撰寫 commit 訊息時使用
+---
+
+依 Conventional Commits 撰寫：type(scope): subject。
+
+subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。
+```
+
+### 命令列選項
+
+```text
+promptex build [--src <目錄>] [--out <目錄>]
+
+  --src <目錄>   宣告檔所在目錄，預設 prompts
+  --out <目錄>   產物輸出目錄，預設當前目錄
+```
+
+### 程式化呼叫
+
+```python
+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`。

promptex_py-0.0.0/README.md

@@ -0,0 +1,85 @@
+# promptex-py（alpha 原型）
+
+promptex 的 Python SDK **最小原型**。目前的能力只有一項：宣告 skill，建置成
+Claude Code 的 `SKILL.md` 產物。
+
+## 這不是什麼
+
+本套件是早期 alpha，**不是**完整的 promptex。正式版的單一套件內含 SDK、核心的
+預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列
+工具只有 `build` 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、
+沒有安裝與所有權登記。plugin 與 adapter 的契約面（`Plugin`、`AdapterContext`、
+`defineTarget` 等）是**介面樁**：型別與簽名逐字複製正式版，方法本體一律拋錯，
+存在的目的是讓第三方擴充能對本套件編譯並發布；要實際執行，工作區得覆寫成本地的
+正式版 SDK。
+
+介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被
+整份取代。
+
+## 安裝
+
+```bash
+pip install --pre promptex-py
+```
+
+需要 Python 3.10 以上。`--pre` 是必要的：預發布版號不會被 pip 預設選中。
+
+## 用法
+
+把宣告寫在 `prompts/` 下：
+
+```python
+# 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 說明變更動機而非變更內容。",
+    ],
+)
+```
+
+建置：
+
+```bash
+promptex build
+```
+
+產出 `./.claude/skills/commit-helper/SKILL.md`：
+
+```text
+---
+name: commit-helper
+description: 當使用者要求撰寫 commit 訊息時使用
+---
+
+依 Conventional Commits 撰寫：type(scope): subject。
+
+subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。
+```
+
+### 命令列選項
+
+```text
+promptex build [--src <目錄>] [--out <目錄>]
+
+  --src <目錄>   宣告檔所在目錄，預設 prompts
+  --out <目錄>   產物輸出目錄，預設當前目錄
+```
+
+### 程式化呼叫
+
+```python
+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`。

promptex_py-0.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "promptex-py"
+# 與 npm／crates.io 側的介面樁同版號；0.0.0 在本生態是「介面樁版本，真實作
+# 尚未發布」的語意，消費端的工作區以 [tool.uv.sources] 覆寫到本地正式版。
+version = "0.0.0"
+description = "promptex 的 Python SDK 最小原型（alpha）：宣告 skill 並投影成 SKILL.md，並提供 plugin 與 adapter 契約的介面樁（只有型別與簽名，沒有實作）"
+requires-python = ">=3.10"
+license = { text = "MIT OR Apache-2.0" }
+readme = "README.md"
+authors = [{ name = "promptex-ai" }]
+keywords = ["prompt", "prompt-engineering", "ai", "llm", "agent", "claude", "skills", "codegen"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Code Generators",
+  # 這一項要成立得靠 src/promptex/py.typed 隨 wheel 一起出貨（PEP 561）：
+  # 型別檢查器對已安裝的套件一律先找標記檔，找不到就整個套件視為無標註。
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/promptex-ai/promptex"
+Repository = "https://github.com/promptex-ai/promptex"
+Issues = "https://github.com/promptex-ai/promptex/issues"
+
+[project.scripts]
+promptex = "promptex.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/promptex"]
+
+[tool.hatch.build]
+# 開發樹本身就是 python-source，直譯器跑過測試留下的 __pycache__ 會被收進
+# wheel。那些 .pyc 綁死在建置機的 Python 版本上，對安裝端無用，卻讓 wheel
+# 的內容清單隨「誰在哪台機器上建的」而變。
+exclude = ["**/__pycache__/**"]

promptex_py-0.0.0/src/promptex/__init__.py

@@ -0,0 +1,168 @@
+"""promptex 的 Python SDK 最小原型（alpha）。
+
+目前的能力只有一條路徑：宣告 skill，投影成 Claude Code 的 SKILL.md。
+正式版的核心綁定、多平台投影、引用與關係圖都不在本原型範圍內。
+
+另有 plugin 與 adapter 契約的**介面樁**：``plugin``／``adapter``／``diag``／``ir``／
+``registry``／``content`` 的公開型別與函式簽名逐字複製正式版，方法本體只要碰到
+註冊表查詢、渲染或投影就拋 ``PromptexStubError``。它們讓第三方擴充能對本套件
+安裝並發布；要實際執行，工作區得以 ``[tool.uv.sources]`` 指向本地的正式版 SDK。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .adapter import (
+    AdapterContext,
+    AdapterEmit,
+    AdapterExtension,
+    DegradeItem,
+    EmitFiles,
+    EmitReport,
+    define_target,
+    format_report,
+    report_payload,
+)
+from .content import MDNode
+from .diag import Diagnostic, format_diagnostic, has_errors
+from .ir import KINDS, Kind
+from .plugin import LockEntry, Plugin, PluginEntry, PrepareContext, TransformContext, ValidateContext
+from .registry import Content, ContentPiece, Ref
+
+__all__ = [
+    "AdapterContext",
+    "AdapterEmit",
+    "AdapterExtension",
+    "CapabilityConfig",
+    "Content",
+    "ContentPiece",
+    "DegradeItem",
+    "Diagnostic",
+    "EmitFiles",
+    "EmitReport",
+    "KINDS",
+    "Kind",
+    "LockEntry",
+    "MDNode",
+    "Plugin",
+    "PluginEntry",
+    "PrepareContext",
+    "Ref",
+    "TransformContext",
+    "ValidateContext",
+    "build",
+    "config",
+    "declared_count",
+    "define_skill",
+    "define_target",
+    "format_diagnostic",
+    "format_report",
+    "has_errors",
+    "render_skill",
+    "report_payload",
+    "skill_path",
+]
+
+__version__ = "0.0.0"
+
+
+@dataclass(frozen=True)
+class CapabilityConfig:
+    """skill 的觸發設定。"""
+
+    when_to_use: str = ""
+
+
+def config(*, when_to_use: str = "") -> CapabilityConfig:
+    """建立觸發設定。與正式版的宣告形態一致，以具名參數承載。"""
+    return CapabilityConfig(when_to_use=when_to_use)
+
+
+@dataclass
+class _Skill:
+    """登記處內的正規化形態。"""
+
+    id: str
+    name: str
+    when_to_use: str
+    content: list[str] = field(default_factory=list)
+
+
+# 模組層級的登記處：宣告散落在多個檔案時，逐一回傳並手動彙整會讓每個檔案
+# 都得認識彙整點。正式版的收集語意相同。
+_registry: list[_Skill] = []
+
+
+def _is_valid_id(value: str) -> bool:
+    """id 是否可安全作為單層目錄名。
+
+    產物路徑由 id 直接組成，不擋下來的話 ``../`` 這類值會把檔案寫到輸出
+    目錄之外。
+    """
+    return bool(value) and "/" not in value and "\\" not in value and value not in {".", ".."}
+
+
+def define_skill(
+    id: str,
+    name: str,
+    *,
+    config: CapabilityConfig | None = None,
+    content: str | list[str] | None = None,
+) -> Ref:
+    """宣告一份 skill。
+
+    宣告本身不寫檔；產物在 :func:`build` 被呼叫時一次產出。
+    """
+    if not _is_valid_id(id):
+        raise ValueError(f"skill id 不可為空、且不可含 `/`、`\\` 或 `..`：{id!r}")
+    pieces = [] if content is None else ([content] if isinstance(content, str) else list(content))
+    _registry.append(
+        _Skill(
+            id=id,
+            name=name,
+            when_to_use=(config or CapabilityConfig()).when_to_use,
+            content=pieces,
+        )
+    )
+    return Ref(kind="skill", id=id)
+
+
+def declared_count() -> int:
+    """目前已登記的宣告數。供呼叫端在建置前自我核對用。"""
+    return len(_registry)
+
+
+def render_skill(skill: _Skill) -> str:
+    """把一份 skill 投影成 SKILL.md 的完整內容。
+
+    frontmatter 的 ``name`` 取 id 而非顯示名稱：平台側以 ``name`` 作為喚起時
+    的識別。
+    """
+    header = f"---\nname: {skill.id}\ndescription: {skill.when_to_use}\n---\n"
+    if not skill.content:
+        return header
+    return header + "\n" + "\n\n".join(skill.content) + "\n"
+
+
+def skill_path(out_dir: str | Path, id: str) -> Path:
+    """一份 skill 在輸出目錄下的產物路徑。"""
+    return Path(out_dir) / ".claude" / "skills" / id / "SKILL.md"
+
+
+def build(out_dir: str | Path) -> list[Path]:
+    """把目前登記的全部宣告投影到輸出目錄，回傳產物路徑。
+
+    呼叫後登記處清空：同一行程內連續建置兩個輸出目錄時，第二次不該重複
+    寫出第一次的內容。
+    """
+    skills = list(_registry)
+    _registry.clear()
+    written: list[Path] = []
+    for skill in skills:
+        path = skill_path(out_dir, skill.id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(render_skill(skill), encoding="utf-8")
+        written.append(path)
+    return written

promptex_py-0.0.0/src/promptex/__main__.py

@@ -0,0 +1,5 @@
+"""讓 ``python -m promptex`` 與 ``promptex`` 執行檔走同一條路徑。"""
+
+from .cli import main
+
+raise SystemExit(main())

promptex_py-0.0.0/src/promptex/_stub.py

@@ -0,0 +1,27 @@
+"""介面樁的統一落點：訊息帶套件名與版號，讓「裝到的是樁」在第一個錯誤就看得
+出來，而不是在某個 ``None`` 或空清單上安靜地繼續。
+
+不從套件根匯出：``PromptexStubError`` 不是正式版的公開面，匯出它會讓樁的公開
+名字多出一個正式版沒有的。
+"""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+_PACKAGE = "promptex-py 0.0.0"
+
+
+class PromptexStubError(NotImplementedError):
+    """呼叫到介面樁時拋出；訊息指名該去哪裡接上真實作。"""
+
+    def __init__(self, what: str) -> None:
+        super().__init__(
+            f"promptex 介面樁（{_PACKAGE}）：`{what}` 沒有實作。"
+            "本版只提供型別與函式簽名讓擴充能編譯；要實際執行，"
+            "請把工作區的 [tool.uv.sources] 指向本地 promptex 框架，或等正式版發布。"
+        )
+
+
+def stub(what: str) -> NoReturn:
+    raise PromptexStubError(what)

promptex_py-0.0.0/src/promptex/adapter.py

@@ -0,0 +1,156 @@
+"""第三方 adapter 的公開介面（介面樁）：型別與方法簽名逐字複製正式版
+``promptex/adapter.py``。
+
+照抄與樁的分界：``define_target`` 只是組一個 dict，照抄；``AdapterContext`` 的
+``degrade``／``unsupported``／``report``／``has_notes`` 只碰自身欄位，照抄；
+``entries``／``render``／``overrides``／``reserved``／``unsupported_override`` 要查
+註冊表或委派核心，本體為樁；``format_report`` 委派核心的報告渲染，本體為樁。
+``report_payload`` 是純序列化，照抄。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional, Sequence, Union
+
+from ._stub import stub
+from .plugin import PluginEntry
+
+
+@dataclass(frozen=True)
+class DegradeItem:
+    """降級或不支援的一筆記錄，與核心 ``adapter::DegradeEntry`` 同型（``node_id``
+    序列化為 ``nodeId``）。欄位名用 ``from_`` 而非 ``from``：後者是 Python
+    關鍵字；序列化時還原為 ``from``。
+    """
+
+    kind: str
+    node_id: str
+    feature: str
+    note: str
+    from_: Optional[str] = None
+    to: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class EmitReport:
+    """一次第三方投影的安裝報告，與內建平台的 ``Report`` 同一形態。"""
+
+    platform: str
+    emitted: Sequence[str]
+    degraded: Sequence[DegradeItem]
+    unsupported: Sequence[DegradeItem]
+
+
+#: 第三方投影的產物表：鍵為相對安裝根的路徑，值依實際內容型態為文字或 ``bytes``。
+EmitFiles = dict[str, Union[str, bytes]]
+
+#: 第三方適配的投影函式：宣告「我是一個新平台」。
+AdapterEmit = Callable[["AdapterContext"], EmitFiles]
+
+#: 平台適配的擴充函式：宣告「我為既有平台補一種產物形態」。
+AdapterExtension = Callable[["AdapterContext", EmitFiles], None]
+
+
+@dataclass
+class AdapterContext:
+    """第三方 adapter 的公開介面：官方與第三方適配使用同一組九個方法。"""
+
+    platform: str
+    select: Optional[dict[str, Any]] = None
+    _degraded: list[DegradeItem] = field(default_factory=list, init=False)
+    _unsupported: list[DegradeItem] = field(default_factory=list, init=False)
+
+    def entries(self, kind: Optional[str] = None) -> list[PluginEntry]:
+        """本平台要產出的節點（省略 kind 即全部）。"""
+        del kind
+        stub("AdapterContext.entries")
+
+    def render(self, entry: PluginEntry, self_path: str, layout: Mapping[str, str]) -> str:
+        """依落點表渲染節點內容：第三個參數是落點對照表，不是回呼函式。"""
+        del entry, self_path, layout
+        stub("AdapterContext.render")
+
+    def overrides(self, entry: PluginEntry) -> Optional[dict[str, Any]]:
+        """本節點為本平台宣告的平台原生鍵覆寫；未宣告或空物件時回傳 ``None``。"""
+        del entry
+        stub("AdapterContext.overrides")
+
+    def reserved(self, entry: PluginEntry) -> Optional[dict[str, str]]:
+        """本節點宣告的框架保留鍵（``promptex:`` 命名空間）；未宣告時回傳 ``None``。"""
+        del entry
+        stub("AdapterContext.reserved")
+
+    def unsupported_override(self, entry: PluginEntry, form: str) -> None:
+        """本節點在本平台的產物沒有承載鍵的位置時，把該筆記進不支援清單。"""
+        del entry, form
+        stub("AdapterContext.unsupported_override")
+
+    def degrade(self, item: DegradeItem) -> None:
+        """記錄能力降級，進安裝報告。"""
+        self._degraded.append(item)
+
+    def unsupported(self, item: DegradeItem) -> None:
+        """記錄平台不支援而未產出的節點，進安裝報告。"""
+        self._unsupported.append(item)
+
+    def report(self, platform: str, emitted: Sequence[str]) -> EmitReport:
+        """把本次累積的降級與不支援併成安裝報告。"""
+        return EmitReport(
+            platform=platform,
+            emitted=list(emitted),
+            degraded=list(self._degraded),
+            unsupported=list(self._unsupported),
+        )
+
+    def has_notes(self) -> bool:
+        """是否累積了任何降級或不支援記錄。"""
+        return bool(self._degraded or self._unsupported)
+
+
+def define_target(
+    platform: str,
+    emit: AdapterEmit,
+    config_schema: Optional[Any] = None,
+    config_schema_locales: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    """第三方套件用本函式建構 target：與內建 ``claude()``／``codex()`` 回傳同一種
+    形狀，多帶一個 ``emit`` 實作。
+    """
+    target: dict[str, Any] = {"platform": platform, "emit": emit}
+    if config_schema is not None:
+        target["config_schema"] = config_schema
+    if config_schema_locales:
+        target["config_schema_locales"] = config_schema_locales
+    return target
+
+
+def _item_payload(item: DegradeItem) -> dict[str, Any]:
+    """一筆記錄的序列化形態，欄位名對齊核心 ``adapter::DegradeEntry``。"""
+    payload: dict[str, Any] = {
+        "kind": item.kind,
+        "nodeId": item.node_id,
+        "feature": item.feature,
+        "note": item.note,
+    }
+    if item.from_ is not None:
+        payload["from"] = item.from_
+    if item.to is not None:
+        payload["to"] = item.to
+    return payload
+
+
+def report_payload(report: EmitReport) -> dict[str, Any]:
+    """``EmitReport`` 轉成核心 ``adapter::Report`` 收的線上形態。"""
+    return {
+        "platform": report.platform,
+        "emitted": list(report.emitted),
+        "degraded": [_item_payload(d) for d in report.degraded],
+        "unsupported": [_item_payload(u) for u in report.unsupported],
+    }
+
+
+def format_report(report: EmitReport) -> str:
+    """格式化為人讀文字：正式版委派核心 ``adapter::Report::format``。"""
+    del report
+    stub("format_report")

promptex_py-0.0.0/src/promptex/cli.py

@@ -0,0 +1,70 @@
+"""promptex 命令列工具（alpha 原型）。
+
+只有一個動詞：``build``。載入來源目錄下的宣告檔，把登記處內的 skill 投影成
+SKILL.md。正式版的其餘動詞（evaluate、declare、config、diagnostics）不在本
+原型範圍內。
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+from . import build, declared_count
+
+
+def _load_source(path: Path) -> None:
+    """以檔案路徑載入一份宣告檔。
+
+    走 importlib 的 spec 載入而非 ``import``：宣告檔住使用者的專案目錄，
+    不在套件搜尋路徑上，也不該為了載入它去改動 ``sys.path``。
+    """
+    module_name = f"_promptex_source_{path.stem}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"無法載入宣告檔：{path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+
+def _collect_sources(src_dir: Path) -> list[Path]:
+    """列出來源目錄下的宣告檔，依路徑排序讓載入順序不隨檔案系統而變。"""
+    return sorted(p for p in src_dir.rglob("*.py") if p.name != "__init__.py")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="promptex", description="promptex（alpha 原型）")
+    sub = parser.add_subparsers(dest="verb", required=True)
+    build_parser = sub.add_parser("build", help="把宣告投影成產物")
+    build_parser.add_argument("--src", default="prompts", help="宣告檔所在目錄，預設 prompts")
+    build_parser.add_argument("--out", default=".", help="產物輸出目錄，預設當前目錄")
+
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+
+    src_dir = Path(args.src).resolve()
+    if not src_dir.is_dir():
+        print(f"找不到來源目錄：{src_dir}", file=sys.stderr)
+        return 1
+
+    sources = _collect_sources(src_dir)
+    if not sources:
+        print(f"來源目錄沒有宣告檔（*.py）：{src_dir}", file=sys.stderr)
+        return 1
+
+    for source in sources:
+        _load_source(source)
+
+    if declared_count() == 0:
+        print(f"載入了 {len(sources)} 份宣告檔，但沒有任何 skill 被宣告。", file=sys.stderr)
+        return 1
+
+    for path in build(Path(args.out).resolve()):
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

promptex_py-0.0.0/src/promptex/content.py

@@ -0,0 +1,38 @@
+"""內容片段的型別（介面樁）：只承載正式版 ``promptex/content.py`` 對外匯出的
+``Piece`` 與 ``MDNode``，逐字複製。建構函式本體（``prose``／``section`` 等）
+不在本樁範圍。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+#: 內容片段：以資料結構表達，不含任何平台的渲染結果。Python 側維持一般 dict
+#: （``{'t': ..., ...}``）表達。
+Piece = dict[str, Any]
+
+
+def _piece_reject_message(piece: Piece) -> str:
+    return (
+        f"內容片段（{piece.get('t')}）不可插入字串或 f-string："
+        "片段是結構化資料，轉換當下只會得到它的 repr，投影階段無從還原。\n"
+        '  內容以清單元素形態承載：content=["前文", bold("重點"), "後文"]'
+    )
+
+
+@dataclass(frozen=True)
+class MDNode:
+    """建構函式的回傳值。包一層是為了與純字串區分。
+
+    覆寫 ``__str__``／``__format__`` 封住字串轉換：片段必須以物件形態保留到
+    投影才能渲染出結構，提前轉換會讓內容靜默退化成一段沒有意義的文字。
+    """
+
+    piece: Piece
+
+    def __str__(self) -> str:  # noqa: D105
+        raise TypeError(_piece_reject_message(self.piece))
+
+    def __format__(self, format_spec: str) -> str:  # noqa: D105
+        raise TypeError(_piece_reject_message(self.piece))

promptex_py-0.0.0/src/promptex/diag.py

@@ -0,0 +1,39 @@
+"""診斷的型別與人讀格式（介面樁）：逐字複製正式版 ``promptex/diag.py`` 的
+``Diagnostic`` 與兩個純函式。診斷本身不含引擎邏輯，因此照抄而非樁；位置捕捉
+（``capture_at``）與相似度計算屬求值期內部工具，不在公開匯出面，不帶。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+#: 嚴重度：'error'（阻斷級中止建置）或 'warning'（非阻斷級列入報告後放行）。
+
+
+@dataclass
+class Diagnostic:
+    """一筆診斷。代碼、訊息、位置三項必含；``at`` 是清單以便同時指出兩處位置。"""
+
+    code: str
+    message: str
+    at: list[str]
+    hint: Optional[str] = None
+    severity: Optional[str] = None
+
+
+def has_errors(diags: list[Diagnostic]) -> bool:
+    """本批診斷是否含阻斷級項目。"""
+    return any((d.severity or "error") == "error" for d in diags)
+
+
+def format_diagnostic(d: Diagnostic) -> list[str]:
+    """一筆診斷的人讀形態，逐行回傳：嚴重度標記（阻斷級 ``✗``、非阻斷級 ``※``）、
+    位置逐一列出、有提示才列提示。
+    """
+    marker = "✗" if (d.severity or "error") == "error" else "※"
+    lines = [f"{marker} {d.code} {d.message}"]
+    lines.extend(f"    at {at}" for at in d.at)
+    if d.hint:
+        lines.append(f"    {d.hint}")
+    return lines

promptex_py-0.0.0/src/promptex/ir.py

@@ -0,0 +1,68 @@
+"""中介表示的型別文件（介面樁）：逐字複製正式版 ``promptex/ir.py`` 的公開型別。
+純型別，執行期只有 ``KINDS`` 這個集合。
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Literal, TypedDict
+
+#: 資源類型：集合封閉，不可由擴充新增。
+Kind = Literal[
+    "skill",
+    "rule",
+    "agent",
+    "hook",
+    "mcp",
+    "instruction",
+    "permission",
+    "resource",
+    "asset",
+    "dir",
+]
+
+#: 與 Kind 同義的執行期可迭代集合，供成員檢查使用。
+KINDS: frozenset[str] = frozenset(
+    {
+        "skill",
+        "rule",
+        "agent",
+        "hook",
+        "mcp",
+        "instruction",
+        "permission",
+        "resource",
+        "asset",
+        "dir",
+    }
+)
+
+
+class RefTarget(TypedDict):
+    """引用目標：類型加識別字的複合鍵。"""
+
+    kind: Kind
+    id: str
+
+
+class Node(TypedDict, total=False):
+    """欄位順序即契約：宣告順序要與 Rust／TypeScript 側一致。"""
+
+    id: str
+    name: str
+    kind: Kind
+    config: dict[str, Any]
+    meta: dict[str, Any]
+    content: list[dict[str, Any]]
+
+
+class Provenance(TypedDict):
+    sourceCommit: str
+    confHash: str
+    engineVersion: str
+
+
+class Ir(TypedDict):
+    version: str
+    provenance: Provenance
+    nodes: List[Node]
+    resources: List[Node]

promptex_py-0.0.0/src/promptex/plugin.py

@@ -0,0 +1,132 @@
+"""擴充機制（plugin）的型別契約（介面樁）：逐字複製正式版 ``promptex/plugin.py``。
+
+三個脈絡類別的方法只是委派建構時注入的 callable，本身沒有引擎邏輯，因此照抄
+而非樁；引擎住框架端注入的函式裡，而樁裡沒有人會建構這些脈絡。``Plugin`` 是
+dataclass，生命週期是欄位持有的 callable，同樣照抄。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Optional, Sequence
+
+from .diag import Diagnostic
+
+
+@dataclass(frozen=True)
+class PluginEntry:
+    """plugin 生命週期看到的節點視圖；Python 側為唯讀快照。"""
+
+    id: str
+    kind: str
+    name: str
+    #: 宣告在源碼中的位置，供診斷指出節點定義於何處。
+    at: str
+    description: Optional[str] = None
+    config: Optional[dict[str, Any]] = None
+    meta: Optional[dict[str, Any]] = None
+    content: Any = None
+
+
+@dataclass(frozen=True)
+class LockEntry:
+    """外部依賴的一筆鎖定記錄。"""
+
+    id: str
+    source: str
+    version: str
+
+
+class PrepareContext:
+    """準備階段看到的框架協助：快取落點與鎖定檔由框架統一提供。"""
+
+    def __init__(
+        self, cache_dir: str, project_root: str, write_lock_fn: Callable[[list[LockEntry]], None]
+    ) -> None:
+        self.cache_dir = cache_dir
+        self.project_root = project_root
+        self._write_lock_fn = write_lock_fn
+
+    def write_lock(self, entries: list[LockEntry]) -> None:
+        """寫入本 plugin 的鎖定區段。"""
+        self._write_lock_fn(entries)
+
+
+class ValidateContext:
+    """解析遍看到的框架協助：唯讀查詢當下註冊表狀態、讀取本 plugin 的自訂
+    參數、取得本輪求值的專案根。
+    """
+
+    def __init__(
+        self,
+        entries_fn: Callable[..., list[PluginEntry]],
+        plugin_name: str,
+        project_root_fn: Callable[[], str],
+    ) -> None:
+        self._entries_fn = entries_fn
+        self._plugin_name = plugin_name
+        self._project_root_fn = project_root_fn
+
+    @property
+    def project_root(self) -> str:
+        """本輪求值的專案根，與 ``PrepareContext.project_root`` 同一個值。"""
+        return self._project_root_fn()
+
+    @property
+    def entries(self) -> list[PluginEntry]:
+        """當下註冊表的全部節點，依 id 排序；每次存取都重新查詢。"""
+        return self._entries_fn()
+
+    def entries_of(self, kind: str) -> list[PluginEntry]:
+        """限定某個 kind 的節點清單。"""
+        return self._entries_fn(kind)
+
+    def params(self, entry: PluginEntry) -> Any:
+        """讀本 plugin 的自訂參數（``meta.plugins[plugin_name]``）；未宣告回傳 ``None``。"""
+        plugins = (entry.meta or {}).get("plugins") or {}
+        return plugins.get(self._plugin_name)
+
+
+class TransformContext(ValidateContext):
+    """改寫遍看到的框架協助：在 ``ValidateContext`` 的唯讀能力之上，加上對
+    節點的疊加型與覆寫型改寫。
+    """
+
+    def __init__(
+        self,
+        entries_fn: Callable[..., list[PluginEntry]],
+        plugin_name: str,
+        append_content_fn: Callable[[PluginEntry, Any], None],
+        patch_config_fn: Callable[[PluginEntry, dict[str, Any]], None],
+        project_root_fn: Callable[[], str],
+    ) -> None:
+        super().__init__(entries_fn, plugin_name, project_root_fn)
+        self._append_content_fn = append_content_fn
+        self._patch_config_fn = patch_config_fn
+
+    def append_content(self, entry: PluginEntry, content: Any) -> None:
+        """對節點的 content 追加一段內容（疊加型改寫）。"""
+        self._append_content_fn(entry, content)
+
+    def patch_config(self, entry: PluginEntry, patch: dict[str, Any]) -> None:
+        """合併進節點的 config（覆寫型改寫）；衝突偵測到鍵的層級。"""
+        self._patch_config_fn(entry, patch)
+
+
+@dataclass
+class Plugin:
+    """一個擴充：dataclass 讓作者以關鍵字引數宣告用得到的生命週期，其餘留
+    ``None``；未宣告的生命週期完全略過。
+    """
+
+    name: str
+    version: Optional[str] = None
+    # 這個擴充作用在哪幾種節點類型；None 即不限。
+    kinds: Optional[Sequence[str]] = None
+    # 本擴充接受哪些建構參數，標準 JSON Schema；純資料，穿得過中介表示的邊界。
+    config_schema: Optional[Any] = None
+    # 各語系的覆蓋層：語系標籤 → 「JSON Pointer → 替換值」的對照。
+    config_schema_locales: Optional[dict[str, Any]] = None
+    prepare: Optional[Callable[[PrepareContext], Awaitable[None]]] = None
+    validate: Optional[Callable[[ValidateContext], list[Diagnostic]]] = None
+    transform: Optional[Callable[[TransformContext], None]] = None

promptex_py-0.0.0/src/promptex/registry.py

@@ -0,0 +1,42 @@
+"""註冊表相關的公開型別（介面樁）：只承載正式版 ``promptex/registry.py`` 對外
+匯出的 ``ContentPiece``／``Content``／``Ref``，逐字複製。註冊表本體（``register``
+／``engine``／求值）不在本樁範圍。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+from .content import MDNode
+
+#: 內容欄位可接受的形態：純文字、建構函式結果、引用，或它們的清單。
+ContentPiece = Union[str, MDNode, "Ref"]
+Content = Union[ContentPiece, list[ContentPiece]]
+
+
+def _ref_reject_message(id_: str, kind: str) -> str:
+    return (
+        f'Ref "{id_}"（{kind}）不可插入字串或 f-string：'
+        "轉換當下會固定為文字，之後無法解析為產物連結。\n"
+        f'  引用以清單元素形態承載：content=["前文", use_resource("{id_}"), "後文"]'
+    )
+
+
+@dataclass(frozen=True)
+class Ref:
+    """宣告函式的回傳值：帶來源資源的類型資訊。同時是引用函式的回傳值，可直接
+    放進另一個節點的 content。
+
+    覆寫 ``__str__``／``__format__`` 封住字串轉換：Ref 必須以物件形態保留到
+    投影才能解析為連結，提前轉換會讓引用靜默退化成文字。
+    """
+
+    id: str
+    kind: str
+
+    def __str__(self) -> str:  # noqa: D105
+        raise TypeError(_ref_reject_message(self.id, self.kind))
+
+    def __format__(self, format_spec: str) -> str:  # noqa: D105
+        raise TypeError(_ref_reject_message(self.id, self.kind))

promptex_py-0.0.0/tests/test_promptex.py

@@ -0,0 +1,78 @@
+"""SDK 的單元測試。以 stdlib 的 unittest 承載，不引入測試框架依賴。
+
+執行：``PYTHONPATH=src python3 -m unittest discover -s tests``
+"""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+import promptex
+from promptex import build, config, declared_count, define_skill, render_skill, skill_path
+
+HEADER = "---\nname: commit-helper\ndescription: 當使用者要求撰寫 commit 訊息時使用\n---\n"
+PARAGRAPHS = [
+    "依 Conventional Commits 撰寫：type(scope): subject。",
+    "subject 用繁體中文、50 字內，不以句號結尾。",
+]
+
+
+class RenderTests(unittest.TestCase):
+    def setUp(self) -> None:
+        promptex._registry.clear()
+
+    def test_renders_frontmatter_and_paragraphs(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+            content=PARAGRAPHS,
+        )
+        expected = HEADER + "\n" + "\n\n".join(PARAGRAPHS) + "\n"
+        self.assertEqual(render_skill(promptex._registry[0]), expected)
+
+    def test_renders_frontmatter_only_when_content_is_empty(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+        )
+        self.assertEqual(render_skill(promptex._registry[0]), HEADER)
+
+    def test_single_string_content_becomes_one_paragraph(self) -> None:
+        define_skill("x", "X", config=config(when_to_use="t"), content="只有一段")
+        self.assertEqual(promptex._registry[0].content, ["只有一段"])
+
+    def test_rejects_ids_that_escape_the_output_directory(self) -> None:
+        with self.assertRaisesRegex(ValueError, "skill id 不可為空"):
+            define_skill("../escape", "X", config=config(when_to_use="t"), content="c")
+
+
+class BuildTests(unittest.TestCase):
+    def setUp(self) -> None:
+        promptex._registry.clear()
+
+    def test_writes_to_claude_skills_layout_and_drains_registry(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+            content=PARAGRAPHS,
+        )
+        self.assertEqual(declared_count(), 1)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            written = build(tmp)
+            self.assertEqual(written, [skill_path(tmp, "commit-helper")])
+            self.assertEqual(
+                Path(written[0]).read_text(encoding="utf-8"),
+                HEADER + "\n" + "\n\n".join(PARAGRAPHS) + "\n",
+            )
+            self.assertEqual(declared_count(), 0)
+            self.assertEqual(build(tmp), [])
+
+
+if __name__ == "__main__":
+    unittest.main()