@laitszkin/apollo-toolkit 2.0.0

package/scripts/install_skills.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<"USAGE"
+Usage:
+  ./scripts/install_skills.sh [codex|openclaw|trae|all]...
+
+Modes:
+  codex     Install symlinks into ~/.codex/skills
+  openclaw  Install symlinks into ~/.openclaw/workspace*/skills
+  trae      Install symlinks into ~/.trae/skills
+  all       Install all supported targets
+
+Optional environment overrides:
+  CODEX_SKILLS_DIR   Override codex skills destination path
+  OPENCLAW_HOME      Override openclaw home path
+  TRAE_SKILLS_DIR    Override trae skills destination path
+  APOLLO_TOOLKIT_HOME Override local install path used in curl/pipe mode
+  APOLLO_TOOLKIT_REPO_URL Override git repository URL used in curl/pipe mode
+USAGE
+}
+
+SCRIPT_SOURCE="${BASH_SOURCE[0]-}"
+TOOLKIT_REPO_URL="${APOLLO_TOOLKIT_REPO_URL:-https://github.com/LaiTszKin/apollo-toolkit.git}"
+TOOLKIT_HOME="${APOLLO_TOOLKIT_HOME:-$HOME/.apollo-toolkit}"
+
+show_banner() {
+  cat <<'BANNER'
++------------------------------------------+
+|              Apollo Toolkit              |
+|      npm installer and skill linker      |
++------------------------------------------+
+BANNER
+}
+
+bootstrap_repo_if_needed() {
+  if [[ -d "$TOOLKIT_HOME/.git" ]]; then
+    git -C "$TOOLKIT_HOME" pull --ff-only >/dev/null
+  else
+    rm -rf "$TOOLKIT_HOME"
+    git clone --depth 1 "$TOOLKIT_REPO_URL" "$TOOLKIT_HOME" >/dev/null
+  fi
+}
+
+if [[ -n "$SCRIPT_SOURCE" && -f "$SCRIPT_SOURCE" ]]; then
+  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+  REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+else
+  # curl/pipe mode: use current directory only when it looks like this repo.
+  if find "$PWD" -mindepth 1 -maxdepth 1 -type d -exec test -f '{}/SKILL.md' ';' -print -quit | grep -q .; then
+    REPO_ROOT="$PWD"
+  else
+    bootstrap_repo_if_needed
+    REPO_ROOT="$TOOLKIT_HOME"
+  fi
+  SCRIPT_DIR="$REPO_ROOT/scripts"
+fi
+SELECTED_MODES=()
+SKILL_PATHS=()
+
+collect_skills() {
+  local dir
+  SKILL_PATHS=()
+  while IFS= read -r dir; do
+    if [[ -f "$dir/SKILL.md" ]]; then
+      SKILL_PATHS+=("$dir")
+    fi
+  done < <(find "$REPO_ROOT" -mindepth 1 -maxdepth 1 -type d | sort)
+
+  if [[ ${#SKILL_PATHS[@]} -eq 0 ]]; then
+    echo "No skill folders found in: $REPO_ROOT" >&2
+    exit 1
+  fi
+}
+
+replace_with_symlink() {
+  local src="$1"
+  local target_root="$2"
+  local name target
+
+  name="$(basename "$src")"
+  target="$target_root/$name"
+
+  mkdir -p "$target_root"
+  if [[ -e "$target" || -L "$target" ]]; then
+    rm -rf "$target"
+  fi
+  ln -s "$src" "$target"
+  echo "[linked] $target -> $src"
+}
+
+install_codex() {
+  local codex_skills_dir
+  codex_skills_dir="${CODEX_SKILLS_DIR:-$HOME/.codex/skills}"
+
+  echo "Installing to codex: $codex_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_symlink "$src" "$codex_skills_dir"
+  done
+}
+
+install_openclaw() {
+  local openclaw_home workspace skills_dir
+  local -a workspaces
+
+  openclaw_home="${OPENCLAW_HOME:-$HOME/.openclaw}"
+
+  workspaces=()
+  while IFS= read -r workspace; do
+    workspaces+=("$workspace")
+  done < <(find "$openclaw_home" -mindepth 1 -maxdepth 1 -type d -name 'workspace*' | sort)
+
+  if [[ ${#workspaces[@]} -eq 0 ]]; then
+    echo "No workspace directories found under: $openclaw_home" >&2
+    exit 1
+  fi
+
+  for workspace in "${workspaces[@]}"; do
+    skills_dir="$workspace/skills"
+    echo "Installing to openclaw workspace: $skills_dir"
+    for src in "${SKILL_PATHS[@]}"; do
+      replace_with_symlink "$src" "$skills_dir"
+    done
+  done
+}
+
+install_trae() {
+  local trae_skills_dir
+  trae_skills_dir="${TRAE_SKILLS_DIR:-$HOME/.trae/skills}"
+
+  echo "Installing to trae: $trae_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_symlink "$src" "$trae_skills_dir"
+  done
+}
+
+add_mode_once() {
+  local mode="$1"
+  local existing
+
+  if [[ ${#SELECTED_MODES[@]} -gt 0 ]]; then
+    for existing in "${SELECTED_MODES[@]}"; do
+      if [[ "$existing" == "$mode" ]]; then
+        return
+      fi
+    done
+  fi
+  SELECTED_MODES+=("$mode")
+}
+
+parse_mode() {
+  local mode="$1"
+
+  case "$mode" in
+    codex|openclaw|trae)
+      add_mode_once "$mode"
+      ;;
+    all)
+      add_mode_once "codex"
+      add_mode_once "openclaw"
+      add_mode_once "trae"
+      ;;
+    *)
+      echo "Invalid mode: $mode" >&2
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+read_choice_from_user() {
+  local prompt="$1"
+  local result
+
+  if [[ -t 0 ]]; then
+    read -r -p "$prompt" result
+  elif [[ -r /dev/tty ]]; then
+    read -r -p "$prompt" result < /dev/tty
+  else
+    echo "Interactive input unavailable. Pass mode arguments (e.g. codex/openclaw/trae/all)." >&2
+    exit 1
+  fi
+
+  printf '%s' "$result"
+}
+
+choose_modes_interactive() {
+  local choice raw_choice
+  local -a choices
+
+  show_banner
+  echo
+  echo "Select install options (comma-separated):"
+  echo "1) codex (~/.codex/skills)"
+  echo "2) openclaw (~/.openclaw/workspace*/skills)"
+  echo "3) trae (~/.trae/skills)"
+  echo "4) all"
+  choice="$(read_choice_from_user 'Enter choice(s) [1-4]: ')"
+
+  IFS=',' read -r -a choices <<< "$choice"
+  for raw_choice in "${choices[@]}"; do
+    raw_choice="${raw_choice//[[:space:]]/}"
+    case "$raw_choice" in
+      1) add_mode_once "codex" ;;
+      2) add_mode_once "openclaw" ;;
+      3) add_mode_once "trae" ;;
+      4) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae" ;;
+      *)
+        echo "Invalid choice: $raw_choice" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  if [[ ${#SELECTED_MODES[@]} -eq 0 ]]; then
+    echo "No install option selected." >&2
+    exit 1
+  fi
+}
+
+resolve_modes() {
+  local mode
+
+  if [[ $# -eq 0 ]]; then
+    choose_modes_interactive
+    return
+  fi
+
+  for mode in "$@"; do
+    parse_mode "$mode"
+  done
+}
+
+main() {
+  local mode
+  SELECTED_MODES=()
+
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    usage
+    exit 0
+  fi
+
+  resolve_modes "$@"
+  collect_skills
+
+  for mode in "${SELECTED_MODES[@]}"; do
+    case "$mode" in
+      codex) install_codex ;;
+      openclaw) install_openclaw ;;
+      trae) install_trae ;;
+      *)
+        usage
+        exit 1
+        ;;
+    esac
+  done
+
+  echo "Done."
+}
+
+main "$@"

package/scripts/validate_openai_agent_config.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Validate agents/openai.yaml for all top-level skills."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+TOP_LEVEL_ALLOWED_KEYS = {"interface", "dependencies", "policy"}
+INTERFACE_REQUIRED_KEYS = {"display_name", "short_description", "default_prompt"}
+INTERFACE_ALLOWED_KEYS = {
+    "display_name",
+    "short_description",
+    "default_prompt",
+    "icon_small",
+    "icon_large",
+    "brand_color",
+}
+HEX_COLOR_PATTERN = re.compile(r"^#[0-9A-Fa-f]{6}$")
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def iter_skill_dirs(root: Path) -> list[Path]:
+    return sorted(path for path in root.iterdir() if path.is_dir() and (path / "SKILL.md").is_file())
+
+
+def extract_frontmatter(content: str) -> dict[str, object]:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("SKILL.md must start with YAML frontmatter delimiter '---'.")
+
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            raw_frontmatter = "\n".join(lines[1:index])
+            parsed = yaml.safe_load(raw_frontmatter)
+            if not isinstance(parsed, dict):
+                raise ValueError("SKILL.md frontmatter must be a YAML mapping.")
+            return parsed
+
+    raise ValueError("SKILL.md frontmatter is missing the closing '---' delimiter.")
+
+
+def require_non_empty_string(container: dict[str, object], key: str, context: str, errors: list[str]) -> None:
+    value = container.get(key)
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{context}: '{key}' must be a non-empty string.")
+
+
+def validate_dependencies(dependencies: object, context: str, errors: list[str]) -> None:
+    if not isinstance(dependencies, dict):
+        errors.append(f"{context}: 'dependencies' must be a mapping.")
+        return
+
+    tools = dependencies.get("tools")
+    if tools is None:
+        return
+    if not isinstance(tools, list):
+        errors.append(f"{context}: 'dependencies.tools' must be a list.")
+        return
+
+    for index, item in enumerate(tools):
+        item_context = f"{context}: dependencies.tools[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{item_context} must be a mapping.")
+            continue
+        require_non_empty_string(item, "type", item_context, errors)
+        require_non_empty_string(item, "value", item_context, errors)
+
+        tool_type = item.get("type")
+        if isinstance(tool_type, str) and tool_type != "mcp":
+            errors.append(f"{item_context}: unsupported tool type '{tool_type}', only 'mcp' is allowed.")
+
+        for optional_key in ("description", "transport", "url"):
+            optional_value = item.get(optional_key)
+            if optional_value is not None and (not isinstance(optional_value, str) or not optional_value.strip()):
+                errors.append(f"{item_context}: '{optional_key}' must be a non-empty string when provided.")
+
+
+def validate_policy(policy: object, context: str, errors: list[str]) -> None:
+    if not isinstance(policy, dict):
+        errors.append(f"{context}: 'policy' must be a mapping.")
+        return
+
+    allow_implicit = policy.get("allow_implicit_invocation")
+    if allow_implicit is not None and not isinstance(allow_implicit, bool):
+        errors.append(
+            f"{context}: 'policy.allow_implicit_invocation' must be a boolean when provided."
+        )
+
+
+def validate_skill(skill_dir: Path) -> list[str]:
+    errors: list[str] = []
+    skill_md = skill_dir / "SKILL.md"
+    openai_yaml = skill_dir / "agents" / "openai.yaml"
+
+    try:
+        skill_frontmatter = extract_frontmatter(skill_md.read_text(encoding="utf-8"))
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        return [f"{skill_md}: unable to read skill name for validation ({exc})."]
+
+    skill_name = skill_frontmatter.get("name")
+    if not isinstance(skill_name, str) or not skill_name.strip():
+        return [f"{skill_md}: frontmatter 'name' must be a non-empty string."]
+
+    if not openai_yaml.is_file():
+        return [f"{openai_yaml}: file is required for every skill."]
+
+    try:
+        parsed = yaml.safe_load(openai_yaml.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        return [f"{openai_yaml}: invalid YAML ({exc})."]
+
+    if not isinstance(parsed, dict):
+        return [f"{openai_yaml}: top-level structure must be a YAML mapping."]
+
+    top_level_keys = set(parsed.keys())
+    unsupported_top_keys = sorted(top_level_keys - TOP_LEVEL_ALLOWED_KEYS)
+    if unsupported_top_keys:
+        errors.append(
+            f"{openai_yaml}: unsupported top-level keys: {', '.join(unsupported_top_keys)}."
+        )
+
+    interface = parsed.get("interface")
+    if not isinstance(interface, dict):
+        errors.append(f"{openai_yaml}: 'interface' must be a mapping.")
+        return errors
+
+    missing_interface_keys = sorted(INTERFACE_REQUIRED_KEYS - set(interface.keys()))
+    if missing_interface_keys:
+        errors.append(
+            f"{openai_yaml}: missing required interface keys: {', '.join(missing_interface_keys)}."
+        )
+
+    unsupported_interface_keys = sorted(set(interface.keys()) - INTERFACE_ALLOWED_KEYS)
+    if unsupported_interface_keys:
+        errors.append(
+            f"{openai_yaml}: unsupported interface keys: {', '.join(unsupported_interface_keys)}."
+        )
+
+    for required_key in sorted(INTERFACE_REQUIRED_KEYS):
+        require_non_empty_string(interface, required_key, str(openai_yaml), errors)
+
+    default_prompt = interface.get("default_prompt")
+    expected_skill_ref = f"${skill_name.strip()}"
+    if isinstance(default_prompt, str) and expected_skill_ref not in default_prompt:
+        errors.append(
+            f"{openai_yaml}: interface.default_prompt must reference '{expected_skill_ref}'."
+        )
+
+    brand_color = interface.get("brand_color")
+    if brand_color is not None:
+        if not isinstance(brand_color, str) or not HEX_COLOR_PATTERN.fullmatch(brand_color):
+            errors.append(f"{openai_yaml}: interface.brand_color must be a hex color like '#1A2B3C'.")
+
+    dependencies = parsed.get("dependencies")
+    if dependencies is not None:
+        validate_dependencies(dependencies, str(openai_yaml), errors)
+
+    policy = parsed.get("policy")
+    if policy is not None:
+        validate_policy(policy, str(openai_yaml), errors)
+
+    return errors
+
+
+def main() -> int:
+    root = repo_root()
+    skill_dirs = iter_skill_dirs(root)
+    if not skill_dirs:
+        print("No top-level skill directories found.")
+        return 1
+
+    all_errors: list[str] = []
+    for skill_dir in skill_dirs:
+        all_errors.extend(validate_skill(skill_dir))
+
+    if all_errors:
+        print("agents/openai.yaml validation failed:")
+        for error in all_errors:
+            print(f"- {error}")
+        return 1
+
+    print(f"agents/openai.yaml validation passed for {len(skill_dirs)} skills.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_skill_frontmatter.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Validate SKILL.md frontmatter for all top-level skills."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+REQUIRED_KEYS = {"name", "description"}
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def iter_skill_dirs(root: Path) -> list[Path]:
+    return sorted(path for path in root.iterdir() if path.is_dir() and (path / "SKILL.md").is_file())
+
+
+def extract_frontmatter(content: str) -> str:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("SKILL.md must start with YAML frontmatter delimiter '---'.")
+
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            return "\n".join(lines[1:index])
+
+    raise ValueError("SKILL.md frontmatter is missing the closing '---' delimiter.")
+
+
+def validate_skill(skill_dir: Path) -> list[str]:
+    errors: list[str] = []
+    skill_md = skill_dir / "SKILL.md"
+
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+    except OSError as exc:
+        return [f"{skill_md}: cannot read file ({exc})."]
+
+    try:
+        frontmatter_text = extract_frontmatter(content)
+    except ValueError as exc:
+        return [f"{skill_md}: {exc}"]
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+    except yaml.YAMLError as exc:
+        return [f"{skill_md}: invalid YAML in frontmatter ({exc})."]
+
+    if not isinstance(frontmatter, dict):
+        return [f"{skill_md}: frontmatter must be a YAML mapping."]
+
+    keys = set(frontmatter.keys())
+    if keys != REQUIRED_KEYS:
+        missing = sorted(REQUIRED_KEYS - keys)
+        extra = sorted(keys - REQUIRED_KEYS)
+        if missing:
+            errors.append(f"{skill_md}: missing required frontmatter keys: {', '.join(missing)}.")
+        if extra:
+            errors.append(f"{skill_md}: unsupported frontmatter keys: {', '.join(extra)}.")
+
+    name = frontmatter.get("name")
+    if not isinstance(name, str) or not name.strip():
+        errors.append(f"{skill_md}: 'name' must be a non-empty string.")
+    else:
+        normalized_name = name.strip()
+        if not NAME_PATTERN.fullmatch(normalized_name):
+            errors.append(
+                f"{skill_md}: 'name' must be kebab-case (lowercase letters, digits, and hyphens)."
+            )
+        if normalized_name != skill_dir.name:
+            errors.append(
+                f"{skill_md}: frontmatter name '{normalized_name}' must match folder name '{skill_dir.name}'."
+            )
+
+    description = frontmatter.get("description")
+    if not isinstance(description, str) or not description.strip():
+        errors.append(f"{skill_md}: 'description' must be a non-empty string.")
+
+    return errors
+
+
+def main() -> int:
+    root = repo_root()
+    skill_dirs = iter_skill_dirs(root)
+    if not skill_dirs:
+        print("No top-level skill directories found.")
+        return 1
+
+    all_errors: list[str] = []
+    for skill_dir in skill_dirs:
+        all_errors.extend(validate_skill(skill_dir))
+
+    if all_errors:
+        print("SKILL.md frontmatter validation failed:")
+        for error in all_errors:
+            print(f"- {error}")
+        return 1
+
+    print(f"SKILL.md frontmatter validation passed for {len(skill_dirs)} skills.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/specs-to-project-docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+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.

package/specs-to-project-docs/README.md

@@ -0,0 +1,57 @@
+# specs-to-project-docs
+
+A documentation skill that consolidates scattered spec files into standardized project docs. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
+
+## Core capabilities
+
+- Scans `spec.md`, `tasks.md`, and `checklist.md` collections as documentation input.
+- Reconciles spec claims against code, config, scripts, and deployment files.
+- Standardizes both new and existing project docs into topic-based files for setup, configuration, architecture, features, and developer onboarding.
+- Provides dedicated reference templates for the top-level README, the documentation index/reference list, and each category document.
+- Deletes superseded spec source files after a successful conversion, unless they still need to stay active or be archived explicitly.
+- Keeps unknown or unverifiable details explicit instead of guessing.
+
+## Repository layout
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+└── references/
+    └── templates/
+        ├── readme.md
+        ├── docs-index.md
+        ├── getting-started.md
+        ├── configuration.md
+        ├── architecture.md
+        ├── features.md
+        └── developer-guide.md
+```
+
+## Default outputs
+
+- `README.md`
+- `docs/README.md`
+- `docs/getting-started.md`
+- `docs/configuration.md`
+- `docs/architecture.md`
+- `docs/features.md`
+- `docs/developer-guide.md`
+
+## Required doc coverage
+
+- Installation and deployment
+- Configuration and environment variables
+- External services and API key acquisition/setup steps when applicable
+- Project architecture
+- Project feature introductions
+- Information developers should understand before changing the project
+
+## Notes
+
+- Prefer code, config, and deployment files over stale spec text when they disagree.
+- If the repository already has docs, rewrite them into the same categorized structure instead of leaving mixed documentation formats.
+- Keep `README.md` short and let `docs/README.md` act as the reference list for deeper topic docs.