@laitszkin/apollo-toolkit 3.11.6 → 3.11.8

package/optimise-skill/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: optimise-skill
+description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+---
+
+## 目標
+在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
+
+## 驗收條件
+- 被優化技能的最終交付產物不受影響
+- 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
+
+## 工作流程
+
+1. 識別交付物
+完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
+
+2. 制定驗收條件
+制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
+
+3. 重寫技能
+將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
+- 技能目標
+- 技能驗收條件
+- 技能工作流程
+- 技能使用範例
+- 技能參考資料索引
+對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
+
+## 範例
+- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+## 參考資料
+- `references/example_skill.md` - 優化後的技能範例，在進行技能優化時必須閱讀並嚴格遵照當中格式 **（必讀）**
+- `references/definition.md` - 技能之中各個區塊的定義 **（必讀）**

package/optimise-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Optimise Skill"
+  short_description: "Rewrite a SKILL.md into a leaner, higher-signal prompt"
+  default_prompt: "Use $optimise-skill to read the target skill and its supporting files, derive the intended deliverable plus acceptance criteria, then rewrite the skill into a tighter goal / acceptance criteria / workflow / examples / references structure without changing the final outcome."

package/optimise-skill/references/definition.md

@@ -0,0 +1,38 @@
+## 驗收條件
+驗收條件是一個技能的**宏觀目標**。其描述的必須是agent完成所有任務之後，交付產物的狀態，如：
+
+**建議實踐**：
+- "嚴格遵守風格規範的前端頁面"
+- "嚴格遵從模板生成的規格文檔"
+- "代碼審查的完整報告總結及改進建議"
+
+**錯誤實踐**：
+- "完成所有規格文檔的閱讀，並理解用戶需求。" - 規格的閱讀是執行步驟，而不是最終的交付產物。
+- "所有風格規範已經被閱讀。" - 同上
+- "所有代碼已經被仔細審查" - 這看似是驗收條件，但實際上因為不可量化，並不是一個好的驗收條件。代碼審查的報告和改進建議是能夠被直觀衡量的交付產物。
+
+## 工作流程
+工作流程是一個技能核心要素。需要專注在告訴agent **「做什麼」**，而不是 **「如何去做」**。
+
+**建議實踐**：
+- "按照本次變更的實際內容，創建符合通用開發規範的git分支並在分支上提交變更。"
+- "在結束任務之前閱讀並確認所有檢查項目是否被勾選為完成。"
+- "閱讀規格文檔之中的 `spec.md` 來完整理解用戶需求"
+
+**錯誤實踐**：
+- "使用 `git diff --stat` 閱讀目前變更。然後使用 `git branch -b <branch_name>` 來創建專屬分支。最後通過 `git commit -m "<commit_message>"` 完成提交。"
+- "在結束任務之前，使用 `cd completion-criteria/` 進入檢查項目所處目錄，通過 `cat checklist.md` 來閱讀整個檢查項目清單，並確認當中的markdown checkboxes是否被勾選為完成。"
+- "使用 `ls` 找到規格文檔目錄，並使用 `cd spec/` 進入規格文檔所出目錄。然後使用 `cat spec.md` 來理解用戶的需求。"
+
+## 範例
+範例是一個技能之中讓效果達到預期的重要基礎。其本質上是通過**對比交付產物在執行工作流程前及執行工作流程後的狀態**，讓agent在調用工作流程自行工作的時候對目標有著清晰的認知，從而避免在執行時成為無頭蒼蠅並在上下文之中迷失。
+
+**建議實踐**：
+用一個用於優化提示詞技能的技能作為示例：
+- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+**錯誤實踐**：
+用一個專門用於前端開發的提示詞技能作為示例：
+- "前端頁面非常混亂。" -> "找到前端頁面所出目錄，列出所有前端頁面檔案，並對前端頁面進行整理" - 前面的找到目錄、列出檔案，這些都是隱含前提，不需要額外列出。我們需要關注並對比的是執行工作流程前後交付物的狀態。
+- "測試覆蓋率低。" -> "執行工作流程補全測試" - 這裏沒有描述好最終的狀態，應該是 `補齊低測試覆蓋率模塊的高價值測試，確保業務邏輯正確無誤。` ，這樣能夠更清晰展現輸入輸出之間的對應關係。

package/optimise-skill/references/example_skill.md

@@ -0,0 +1,36 @@
+---
+name: optimise-skill
+description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+---
+
+## 目標
+在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
+
+## 驗收條件
+- 被優化技能的最終交付產物不受影響
+- 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
+
+## 工作流程
+
+1. 識別交付物
+完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
+
+2. 制定驗收條件
+制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
+
+3. 重寫技能
+將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
+- 技能目標
+- 技能驗收條件
+- 技能工作流程
+- 技能使用範例
+- 技能參考資料索引
+對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
+
+## 範例
+- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+## 參考資料
+- `references/example_skill.md` - 優化後的技能範例，在進行技能優化時必須閱讀並嚴格遵照當中格式 **（必讀）**
+- `references/definition.md` - 技能之中各個區塊的定義 **（必讀）**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.11.6",
+  "version": "3.11.8",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/read-github-issue/SKILL.md

@@ -33,44 +33,16 @@ description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use whe
 
 ### 2) Find candidate issues with the bundled CLI
 
-- Preferred command:
-
-```bash
-apltk find-github-issues --limit 50 --state open
-```
-
-- Optional filters:
-  - `--repo owner/name`
-  - `--label bug`
-  - `--search "panic in parser"`
+- Use `apltk find-github-issues --help` as the live command reference for filters, output modes, and examples.
 - Raw `gh` fallback when the script is missing or broken:
-
-```bash
-gh issue list --limit 50 --state open
-```
-
-- Add `--repo <owner>/<repo>`, `--label <label>`, or `--search "<text>"` as needed.
+- `gh issue list --limit 50 --state open`
 - If the issue target is still unclear, present top candidates and ask which issue number or URL should be inspected next.
 
 ### 3) Read a specific issue in detail
 
-- Preferred command:
-
-```bash
-apltk read-github-issue 123 --comments
-```
-
-- Optional flags:
-  - `--repo owner/name`
-  - `--json`
-  - `--comments`
+- Use `apltk read-github-issue --help` as the live command reference for issue selection, comments, JSON output, and examples.
 - Raw `gh` fallback when the script is missing or broken:
-
-```bash
-gh issue view 123 --comments
-```
-
-- Use `--repo <owner>/<repo>` when targeting a different repository.
+- `gh issue view 123 --comments`
 - Use the returned title, body, labels, assignees, state, timestamps, and comments to summarize the issue precisely.
 
 ### 4) Summarize gaps before any follow-up action
@@ -78,18 +50,6 @@ gh issue view 123 --comments
 - Identify missing acceptance criteria, repro details, affected components, or environment context.
 - If issue text and comments are insufficient, state exactly what is missing instead of inventing a fix plan.
 
-## Included CLI
-
-### `apltk find-github-issues`
-
-- Purpose: consistent remote issue listing via `gh issue list`.
-- Outputs a readable table by default, or JSON with `--output json`.
-- Uses only GitHub CLI so it reflects remote GitHub state.
-- Treat it as a convenience wrapper, not a hard dependency.
-
-### `apltk read-github-issue`
+## CLI reference
 
-- Purpose: deterministic issue detail retrieval via `gh issue view`.
-- Outputs either a human-readable summary or full JSON for downstream automation.
-- Can include issue comments so the agent can read the latest discussion before taking any other step.
-- Treat it as a convenience wrapper, not a hard dependency.
+Use `apltk find-github-issues --help` and `apltk read-github-issue --help` as the authoritative command references. This skill keeps the retrieval workflow and fallback rules, not the flag catalog.

package/resolve-review-comments/SKILL.md

@@ -40,21 +40,12 @@ description: Read GitHub pull request review comments, analyze each thread, deci
 
 - If user provides PR number, use it directly.
 - If user does not provide PR number, infer from current branch context.
-
-```bash
-apltk review-threads list --repo <owner>/<repo> --pr <number>
-apltk review-threads list
-```
+- Use `apltk review-threads --help` as the live command reference for PR inference and explicit repo selection.
 
 ## 2) Read unresolved review threads
 
 Use table view for quick scan, then JSON when you need full details.
 
-```bash
-apltk review-threads list --pr <number> --state unresolved --output table
-apltk review-threads list --pr <number> --state unresolved --output json > /tmp/pr_threads.json
-```
-
 The JSON output contains `thread_id`, `path`, `line`, and comment bodies for decision and resolution.
 
 ## 3) Decide adopt vs reject
@@ -91,16 +82,7 @@ Track adopted thread IDs in a JSON file:
 ## 7) Resolve addressed threads
 
 Resolve only threads you actually addressed in code.
-
-```bash
-apltk review-threads resolve --pr <number> --thread-id-file adopted_threads.json
-```
-
-Optional preview without mutating GitHub state:
-
-```bash
-apltk review-threads resolve --pr <number> --thread-id-file adopted_threads.json --dry-run
-```
+- Use `apltk review-threads --help` as the live command reference for listing, resolving, dry-run behavior, and thread-id file input.
 
 ## 8) Handle non-adopted comments
 
@@ -108,10 +90,6 @@ apltk review-threads resolve --pr <number> --thread-id-file adopted_threads.json
 - Reply with a concise technical reason and, if needed, a proposed follow-up.
 - Never resolve rejected or unhandled feedback threads.
 
-## CLI
-
-### `apltk review-threads`
+## CLI reference
 
-- `list`: fetch PR review threads via GitHub GraphQL (`gh api graphql`), supports repo/PR inference.
-- `resolve`: resolve selected review threads by thread IDs.
-- Supports thread IDs from flags, JSON files, or `--all-unresolved`.
+Use `apltk review-threads --help` as the authoritative command reference. This skill preserves the adopt/reject workflow and submission rules, not the flag catalog.

package/scripts/validate_openai_agent_config.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import argparse
 import re
 import sys
 from pathlib import Path
@@ -21,6 +22,11 @@ INTERFACE_ALLOWED_KEYS = {
 }
 HEX_COLOR_PATTERN = re.compile(r"^#[0-9A-Fa-f]{6}$")
 
+HELP_EPILOG = """Examples:
+  apltk validate-openai-agent-config
+    Result: prints either a pass summary or one error per invalid agents/openai.yaml file.
+"""
+
 
 def repo_root() -> Path:
     return Path(__file__).resolve().parent.parent
@@ -169,7 +175,16 @@ def validate_skill(skill_dir: Path) -> list[str]:
     return errors
 
 
-def main() -> int:
+def build_parser() -> argparse.ArgumentParser:
+    return argparse.ArgumentParser(
+        description="Validate agents/openai.yaml for all top-level skills.",
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    build_parser().parse_args(argv)
     root = repo_root()
     skill_dirs = iter_skill_dirs(root)
     if not skill_dirs:

package/scripts/validate_skill_frontmatter.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import argparse
 import re
 import sys
 from pathlib import Path
@@ -13,6 +14,11 @@ NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 REQUIRED_KEYS = {"name", "description"}
 MAX_DESCRIPTION_LENGTH = 1024
 
+HELP_EPILOG = """Examples:
+  apltk validate-skill-frontmatter
+    Result: prints either a pass summary or one error per invalid top-level SKILL.md frontmatter file.
+"""
+
 
 def repo_root() -> Path:
     return Path(__file__).resolve().parent.parent
@@ -91,7 +97,16 @@ def validate_skill(skill_dir: Path) -> list[str]:
     return errors
 
 
-def main() -> int:
+def build_parser() -> argparse.ArgumentParser:
+    return argparse.ArgumentParser(
+        description="Validate SKILL.md frontmatter for all top-level skills.",
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    build_parser().parse_args(argv)
     root = repo_root()
     skill_dirs = iter_skill_dirs(root)
     if not skill_dirs:

package/spec-to-project-html/SKILL.md

@@ -21,11 +21,7 @@ description: >-
 - **MUST** obey the semantic rules from `init-project-html/SKILL.md`:
   - Sub-module pages stay self-only — express cross-boundary interactions via **edges** (cross-feature or intra-feature), never as sub-module page prose.
   - Feature pages stay lightweight — cross-sub-module choreography belongs in **edges**, not in `dataflow` prose that pretends to cross features.
-- **MUST** reconcile deltas through the CLI families described in **`--help`**:
-  - Structural changes → `feature` / `submodule` (**add** / **set** / **remove** as appropriate).
-  - Per-sub-module rows → `function`, `variable`, `dataflow`, `error` (**add** / **remove** / **reorder** for dataflow where supported).
-  - Seams → `edge` **add** / **remove** (prefer stable **`--id`** when you may remove the same edge later).
-  - **`submodule remove`** / **`feature remove`** in spec mode populate removal manifests so `diff` can show **removed** pages; renames are usually **remove old slug + add new slug** so the viewer shows remove + add rather than a silent overwrite.
+- **MUST** reconcile deltas through the CLI families described in **`apltk architecture --help`**. Keep the meaning in this skill, but take the exact verbs, subverbs, and flags from the CLI itself.
 - **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite role/purpose to flag “out of spec scope”.
 - **MUST** scope reads to the **affected feature modules** from the spec/design diff (plus any feature owning the other end of a cross-feature edge into an affected one). **Subagents own intra-feature overlay writes; the main agent owns cross-feature seams — after all subagents finish:**
   - Dispatch **one write-capable subagent per affected feature**. Each applies every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>` (exact flags: **`--help`**). Each returns **ONLY** a structured summary: sub-module change list, outbound boundary changes (cross-feature edges to add/change/remove), and any `planned` / `gap` markers.
@@ -67,15 +63,7 @@ Dispatch one **write-capable subagent per affected feature**. Each subagent owns
 > - Run `apltk architecture validate --spec <spec_dir>` before returning.
 > - **Return ONLY**: (i) sub-module change list, (ii) outbound boundary changes (cross-feature edges add/change/remove with endpoints and suggested kind/label), (iii) any `planned` / `gap` flags for `meta.summary`.
 
-**After every subagent has completed**, the main agent declares **only** cross-feature seams, then renders and validates:
-
-```bash
-# exact flags per edge: see --help
-apltk architecture edge add --spec <spec_dir> --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture edge remove --spec <spec_dir> --id <stable_id> --no-render
-apltk architecture render --spec <spec_dir>
-apltk architecture validate --spec <spec_dir>
-```
+**After every subagent has completed**, the main agent declares **only** the cross-feature seams through `apltk architecture ... --spec <spec_dir>`, then renders and validates the overlay.
 
 - **Pause →** Do `planned` / `gap` markers read consistently across affected sub-modules?
 - The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.

package/update-project-html/SKILL.md

@@ -44,15 +44,9 @@ The atlas update is only complete when **all** of the following hold:
 3. Macro acceptance criteria from `init-project-html` still hold: cross-boundary interaction expressed as `call`/`return`/`data-row`/`failure` edges (never sub-module page prose); each touched sub-module’s internal diagram has function-to-function flow plus declared variable reads/writes for non-trivial steps.
 4. The handover report cites: chosen diff scope (literal commands), affected feature list, per-feature mutation counts, skipped diff buckets (with reasons), and confirmation that **all subagents completed before cross-feature wiring**.
 
-## How to use `apltk architecture`
+## CLI reference
 
-**Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). Same families as `init-project-html`:
-
-- `feature` / `submodule` — structural mutations (use **`set`** for label/role updates, **`remove`** when code deleted the entry point, **`add`** when the diff introduced a new module).
-- `function` / `variable` / `dataflow` / `error` — per-sub-module rows. Declare new symbols **before** referencing them in `dataflow`. Use the row-level `remove` (see `--help`) to delete obsolete rows the diff dropped.
-- `edge` — intra- or cross-feature seams. Prefer stable **`--id`** when re-applying the same edge after a mutation cycle. `kind` ∈ `call` | `return` | `data-row` | `failure`.
-- `meta` / `actor` — only when the diff actually changed the macro narrative (e.g. summary now needs to record the diff scope or new omissions).
-- `render` (when you batched with `--no-render`) → `validate` → done.
+Use `apltk architecture --help` and deeper `apltk architecture <verb> [subverb] --help` pages as the authoritative command references. This skill keeps the diff-filtering rules, subagent ownership rules, and base-atlas-only scope; it does not duplicate the flag catalog.
 
 This skill **never** uses `--spec`. If the user wants overlay diagrams for a planning doc, redirect to **`spec-to-project-html`**.
 
@@ -90,17 +84,7 @@ Dispatch one **write-capable** subagent per affected feature. Hand each subagent
 > - Run **`apltk architecture validate`** before returning.
 > - **Return ONLY**: (i) sub-module change list (slug + change kind + one-line reason) and (ii) outbound boundary deltas (cross-feature edges to add/change/remove with endpoints + suggested kind/label). No source dumps.
 
-**Orchestrator — after every subagent has completed:**
-
-```bash
-# only when meta.summary needs to record the diff scope or new omissions
-apltk architecture meta set --summary "..." --no-render
-# one edge mutation per cross-feature interaction reported by the subagents
-apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture edge remove --id <stable_id> --no-render
-apltk architecture render
-apltk architecture validate
-```
+**Orchestrator — after every subagent has completed:** apply only the cross-feature `apltk architecture` mutations that the subagents reported, then render and validate the base atlas.
 
 The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
    - **Pause →** Did every subagent return — or am I about to wire cross-feature edges from partial summaries?

package/weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift

@@ -3,6 +3,21 @@
 import Foundation
 import PDFKit
 
+let helpText = """
+apltk extract-pdf-text-pdfkit — extract PDF text with macOS PDFKit.
+
+Usage:
+  apltk extract-pdf-text-pdfkit /absolute/path/to/source.pdf
+  swift weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
+
+Use this when:
+  - You need a simple macOS PDFKit-based text extraction fallback.
+
+Examples:
+  apltk extract-pdf-text-pdfkit /absolute/path/to/source.pdf
+    Result: prints `PDF_PATH=...`, `PAGE_COUNT=...`, and one `=== PAGE N ===` section per extracted page.
+"""
+
 struct Arguments {
     let pdfPath: String
 }
@@ -15,7 +30,7 @@ enum ExtractionError: Error, CustomStringConvertible {
     var description: String {
         switch self {
         case .missingPath:
-            return "Usage: swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf"
+            return "Usage: swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf\nRun with --help for the full command guide."
         case .unsupportedPlatform:
             return "PDFKit extraction is only supported on macOS."
         case .unreadablePDF(let path):
@@ -24,19 +39,31 @@ enum ExtractionError: Error, CustomStringConvertible {
     }
 }
 
-func parseArguments() throws -> Arguments {
+enum ParseResult {
+    case help
+    case arguments(Arguments)
+}
+
+func parseArguments() throws -> ParseResult {
     let args = Array(CommandLine.arguments.dropFirst())
+    if args.contains("--help") || args.contains("-h") {
+        return .help
+    }
     guard let pdfPath = args.first, !pdfPath.isEmpty else {
         throw ExtractionError.missingPath
     }
-    return Arguments(pdfPath: pdfPath)
+    return .arguments(Arguments(pdfPath: pdfPath))
 }
 
 func main() throws {
     #if !os(macOS)
     throw ExtractionError.unsupportedPlatform
     #else
-    let arguments = try parseArguments()
+    switch try parseArguments() {
+    case .help:
+        print(helpText)
+        return
+    case .arguments(let arguments):
     let pdfURL = URL(fileURLWithPath: arguments.pdfPath)
 
     guard let document = PDFDocument(url: pdfURL) else {
@@ -60,6 +87,7 @@ func main() throws {
             print(text)
         }
     }
+    }
     #endif
 }
 

package/maintain-skill-catalog/README.md

@@ -1,18 +0,0 @@
-# maintain-skill-catalog
-
-Maintain a repository of installable skills by auditing skill definitions, dependency declarations, shared conventions, and catalog validation.
-
-## Core capabilities
-
-- Scans top-level skills before adding or splitting new ones to avoid duplicate scope.
-- Audits standardized `## Dependencies` sections and separates vendored, local-only, external, and alias dependencies.
-- Syncs catalog docs such as `README.md` and `AGENTS.md/CLAUDE.md` with actual skill capabilities.
-- Catches catalog-wide validation issues like missing `agents/openai.yaml` files or stale prompt references.
-- Encodes user corrections into durable catalog rules so the same classification mistakes do not repeat.
-
-## Typical triggers
-
-- Standardize all skills to one dependency format.
-- Check which skills rely on external skills and document how to install them.
-- Split repeated workflow steps into a new shared skill.
-- Fix skill-catalog CI failures caused by missing metadata or agent config files.

package/maintain-skill-catalog/SKILL.md

@@ -1,72 +0,0 @@
----
-name: maintain-skill-catalog
-description: >-
-  Maintain this SKILL catalog repo: reconcile `SKILL.md` frontmatter/`Dependencies`, `agents/openai.yaml`, README inventory, classify vendored vs external vs unpublished-local aliases, prefer extracting shared workflows over duplicating long prose, and always rerun `apltk validate-skill-frontmatter` plus `apltk validate-openai-agent-config` before finishing—never invent package names or installers for unverified deps.
-  Use when CI metadata breaks, users ask to “sync skills”, or dependency docs drift. Do not use for random application repos that are not this catalog layout.
-  Bad: marketing a `~/.claude` draft as an npm dependency… Good: label it “local optional” and link once in README instead of pasting the blurb into five skills…
----
-
-# Maintain Skill Catalog
-
-## Dependencies
-
-- Required: none.
-- Conditional: `find-skills` when a dependency is external and the installation source is unknown.
-- Optional: `skill-creator` when extracting a repeated workflow into a new shared skill or heavily reshaping a skill.
-- Fallback: If an external dependency cannot be verified, **MUST** document unknowns honestly—**MUST NOT** invent package names, install commands, or skill aliases.
-
-## Non-negotiables
-
-- **MUST** read actual skill directories, validator scripts (`scripts/validate_*.py`, CI), `README.md`, and `agents/openai.yaml` patterns **before** reclassifying dependencies or rewriting catalog prose.
-- **MUST** treat each skill’s `## Dependencies` block as authoritative for skill-to-skill references; reconcile docs to match folders, not the reverse by guess.
-- **MUST** classify each dependency edge as: vendored-in-repo · local unpublished (not advertised as external) · external-with-install-guidance · alias-only (explain, don’t duplicate as separate dep).
-- **MUST NOT** duplicate skills or paste long prose into README without verifying whether a narrower edit or extraction fixes the repetition.
-- **MUST NOT** advertise a colleague’s unpublished `~/.codex/skills/...` name as if it were an npm-installable artifact unless verified.
-- After metadata or agent-config edits, **MUST** run **`apltk validate-skill-frontmatter`** and **`apltk validate-openai-agent-config`** (or fail the session with explanation if CLI unavailable)—**MUST NOT** declare the catalog consistent while validators fail.
-- If validator failures reveal a **systemic** gap, **MUST** prefer tightening the validator/CI in the **same** change set when appropriate, not only patching one skill ad hoc.
-
-## Standards (summary)
-
-- **Evidence**: Folders + scripts + frontmatter reality; optional `~/.codex/skills` spot-check for external names.
-- **Execution**: Inventory → classify → minimal focused edits → validate → report.
-- **Quality**: One skill one purpose; naming matches folder; agent configs synchronized.
-- **Output**: Updated lists/docs + green validators + explicit unknowns.
-
-## Workflow
-
-**Chain-of-thought:** Answer **`Pause →`** before moving to the next subsection; validator red **MUST** block “done.”
-
-### 1) Inventory
-
-- Enumerate top-level skill dirs (`SKILL.md` present); read touched `SKILL.md` files before inventing merges or new skills.
-- Read `README.md`, `AGENTS.md`/`CLAUDE.md`, and existing dependency notes.
-  - **Pause →** Is the requested change already satisfied by renaming or merging **existing** skill text instead of adding a sibling skill?
-  - **Pause →** Which validator script actually enforces description length and keys—did I open its source?
-
-### 2) Audit dependencies and conventions
-
-- Align `## Dependencies` across skills with shared vocabulary (`Required` / `Conditional` / `Optional` / `Fallback`).
-- Exact external strings only—verify spelling/plural vs installed tree.
-- Repeated workflows ⇒ prefer **extract** to new skill (`skill-creator`) over copy-paste.
-  - **Pause →** Would classifying dep X as “external” confuse installers—could it actually be repo-vendored or optional?
-
-### 3) Apply catalog edits
-
-- Minimal diffs; update `README` skill lists and external-dep sections **only when** inventory changed facts.
-- New shared skill: kebab-case folder = frontmatter `name`; add `agents/openai.yaml` following neighbors.
-  - **Pause →** Did I treat a **template** path under `references/` as a runtime skill—classification error?
-
-### 4) Validate
-
-- Run `apltk validate-skill-frontmatter` and `apltk validate-openai-agent-config`. If installer/discovery scripts changed behavior, smoke the paths they document.
-  - **Pause →** Any skill missing `agents/openai.yaml` or stale tool names—still acceptable for this repo’s rules?
-
-### 5) Report
-
-- Skills touched, conventions updated, external deps verified vs unknown; encode user-stated repo rules into skill or README so regressions recur less.
-
-## Sample hints
-
-- **Classification**: Skill A says `Conditional: Foo` but `Foo` lives only under `~/.claude/` unpublished → document as **local optional**, not “install Foo from npm.”
-- **Validator**: frontmatter `description` 1100 chars → expect **fail** if limit 1024—fix text, don’t disable check.
-- **Anti-pattern**: “We should mention skill X everywhere” → add **once** to README index + Dependencies of callers, not five duplicate paragraphs.

package/maintain-skill-catalog/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "maintain-skill-catalog"
-  short_description: "Audit and keep a skill repository consistent"
-  default_prompt: "Use $maintain-skill-catalog to audit top-level skills, classify internal versus external dependencies, sync catalog docs, extract repeated workflows into shared skills when justified, and run repository validators before finishing."