matt-bat/got-skills / skills/help
help
VerifiedExplain the installed Agent Command Center skillpack when the user sends --help, including every active skill, activation marker, supported command, and concise behavior description. Also supplies the exact one-line startup hint required when the pack is first loaded into a conversation; do not activate for unrelated help requests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| agents/openai.yaml | config | 206 B |
| references/runtime-protocol.md | markdown | 3.1 KB |
| scripts/runtime_adapter.py | script | 14.3 KB |
scripts/runtime_adapter.py
View on GitHub#!/usr/bin/env python3
"""Process Agent Command Center lifecycle and exact-command events.
Conversation lifecycle data stays in the event state. User-controlled mode
preferences are persisted locally so an explicit toggle survives conversations.
Only booleans are stored; no message content or credentials are written.
"""
from __future__ import annotations
import argparse
import copy
import hashlib
import json
import shlex
import sys
import os
import tempfile
from pathlib import Path
from typing import Any, Mapping, Sequence
SCHEMA_VERSION = 1
STARTUP_HINT = "send --help to learn more about available tools in agent-command-center"
QUIZME_OPTIONS = frozenset({"--mc", "--one-at-a-time", "--confirm", "--record"})
PREFERENCES_ENV = "AGENT_COMMAND_CENTER_PREFERENCES"
DEFAULT_STATE: dict[str, Any] = {
"schema_version": SCHEMA_VERSION,
"startup_hint_emitted": False,
"clean_slate": False,
"quizme": {
"enabled": False,
"multiple_choice": False,
"one_at_a_time": False,
"confirm": False,
"record": False,
},
"internal_lang": {"internal": False, "response": False},
"user_run_scripts": False,
}
class RuntimeProtocolError(ValueError):
"""Raised when a host supplies a malformed runtime event or state."""
def _closed_keys(value: Mapping[str, Any], allowed: set[str], label: str) -> None:
extras = sorted(set(value) - allowed)
if extras:
raise RuntimeProtocolError(f"{label} contains unsupported fields: {', '.join(extras)}")
def normalize_state(value: Mapping[str, Any] | None) -> dict[str, Any]:
"""Return a validated deep copy of runtime state."""
if value is None:
return copy.deepcopy(DEFAULT_STATE)
if not isinstance(value, Mapping):
raise RuntimeProtocolError("state must be an object")
_closed_keys(
value,
{"schema_version", "startup_hint_emitted", "clean_slate", "quizme", "internal_lang", "user_run_scripts"},
"state",
)
if value.get("schema_version") != SCHEMA_VERSION:
raise RuntimeProtocolError(f"state.schema_version must equal {SCHEMA_VERSION}")
result = copy.deepcopy(DEFAULT_STATE)
for name in ("startup_hint_emitted", "clean_slate"):
if not isinstance(value.get(name), bool):
raise RuntimeProtocolError(f"state.{name} must be boolean")
result[name] = value[name]
if "user_run_scripts" in value:
if not isinstance(value["user_run_scripts"], bool):
raise RuntimeProtocolError("state.user_run_scripts must be boolean")
result["user_run_scripts"] = value["user_run_scripts"]
for group, fields in {
"quizme": {"enabled", "multiple_choice", "one_at_a_time", "confirm", "record"},
"internal_lang": {"internal", "response"},
}.items():
nested = value.get(group)
if not isinstance(nested, Mapping):
raise RuntimeProtocolError(f"state.{group} must be an object")
_closed_keys(nested, fields, f"state.{group}")
missing = sorted(fields - set(nested))
if missing:
raise RuntimeProtocolError(f"state.{group} is missing fields: {', '.join(missing)}")
for name in fields:
if not isinstance(nested[name], bool):
raise RuntimeProtocolError(f"state.{group}.{name} must be boolean")
result[group][name] = nested[name]
if result["quizme"]["record"] and not result["quizme"]["confirm"]:
raise RuntimeProtocolError("state.quizme.record requires state.quizme.confirm")
return result
def _preferences_path() -> Path:
configured = os.environ.get(PREFERENCES_ENV)
return Path(configured).expanduser() if configured else Path.home() / ".config" / "agent-command-center" / "preferences.json"
def _preference_state() -> dict[str, Any]:
path = _preferences_path()
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError:
return copy.deepcopy(DEFAULT_STATE)
except (OSError, json.JSONDecodeError) as exc:
raise RuntimeProtocolError(f"cannot read persisted preferences: {exc}") from exc
if not isinstance(payload, Mapping):
raise RuntimeProtocolError("persisted preferences must be an object")
return normalize_state({"schema_version": SCHEMA_VERSION, "startup_hint_emitted": False, **payload})
def _persist_preferences(state: Mapping[str, Any]) -> None:
path = _preferences_path()
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
payload = {"schema_version": SCHEMA_VERSION, "clean_slate": state["clean_slate"], "quizme": state["quizme"], "internal_lang": state["internal_lang"], "user_run_scripts": state["user_run_scripts"]}
fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent), text=True)
try:
os.fchmod(fd, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
json.dump(payload, handle, indent=2, sort_keys=True)
handle.write("\n")
handle.flush()
os.fsync(handle.fileno())
os.replace(temporary, path)
except OSError as exc:
try:
os.unlink(temporary)
except OSError:
pass
raise RuntimeProtocolError(f"cannot persist preferences: {exc}") from exc
def _active_mode_skills(state: Mapping[str, Any]) -> list[str]:
active: list[str] = []
if state["clean_slate"]:
active.append("clean-slate")
if state["quizme"]["enabled"]:
active.append("quizme-mode")
if state["internal_lang"]["internal"] or state["internal_lang"]["response"]:
active.append("internal-lang")
if state["user_run_scripts"]:
active.append("user-run-scripts")
return active
def _descriptor_patch(state: Mapping[str, Any], command_skill: str | None, help_requested: bool) -> dict[str, Any]:
explicit = _active_mode_skills(state)
if command_skill and command_skill != "help" and command_skill not in explicit:
explicit.append(command_skill)
patch: dict[str, Any] = {}
if help_requested:
patch["action"] = {"help_requested": True}
if explicit:
patch["constraints"] = {"explicit_skills": explicit}
return patch
def apply_descriptor_patch(descriptor: Mapping[str, Any], patch: Mapping[str, Any]) -> dict[str, Any]:
"""Apply a runtime patch without dropping host-normalized explicit skills."""
if not isinstance(descriptor, Mapping) or not isinstance(patch, Mapping):
raise RuntimeProtocolError("descriptor and patch must be objects")
result = copy.deepcopy(dict(descriptor))
action = result.get("action")
constraints = result.get("constraints")
if not isinstance(action, dict) or not isinstance(constraints, dict):
raise RuntimeProtocolError("descriptor requires action and constraints objects")
patch_action = patch.get("action", {})
patch_constraints = patch.get("constraints", {})
if not isinstance(patch_action, Mapping) or not isinstance(patch_constraints, Mapping):
raise RuntimeProtocolError("descriptor patch action and constraints must be objects")
action.update(copy.deepcopy(dict(patch_action)))
additions = patch_constraints.get("explicit_skills", [])
existing = constraints.get("explicit_skills")
if not isinstance(existing, list) or not all(isinstance(item, str) for item in existing):
raise RuntimeProtocolError("descriptor.constraints.explicit_skills must be an array of strings")
if not isinstance(additions, list) or not all(isinstance(item, str) for item in additions):
raise RuntimeProtocolError("patch.constraints.explicit_skills must be an array of strings")
constraints["explicit_skills"] = list(dict.fromkeys([*existing, *additions]))
return result
def _parse_message(message: str, state: dict[str, Any]) -> tuple[str | None, bool, list[str], bool]:
"""Apply an exact command and return skill, consumed, notices, help flag."""
stripped = message.strip()
if not stripped.startswith("--"):
return None, False, [], False
try:
tokens = shlex.split(stripped)
except ValueError as exc:
return None, False, [f"Malformed command was not consumed: {exc}."], False
if not tokens:
return None, False, [], False
command, *arguments = tokens
notices: list[str] = []
if command == "--help":
if arguments:
notices.append("Unsupported --help arguments; send exact command --help.")
return None, False, notices, False
return "help", True, notices, True
if command == "--clean-slate":
if not arguments:
state["clean_slate"] = True
notices.append("Clean-slate mode is on.")
elif arguments == ["off"]:
state["clean_slate"] = False
notices.append("Clean-slate mode is off.")
else:
notices.append("Unsupported --clean-slate arguments; expected no argument or 'off'.")
return None, False, notices, False
return "clean-slate", True, notices, False
if command == "--quizme":
unsupported = sorted(set(arguments) - QUIZME_OPTIONS)
if unsupported:
notices.append(
"Unsupported --quizme arguments; the command was not applied: "
+ " ".join(unsupported)
+ "."
)
return None, False, notices, False
supported = set(arguments) & QUIZME_OPTIONS
quizme = state["quizme"]
if not supported:
quizme["enabled"] = not quizme["enabled"]
for name in ("multiple_choice", "one_at_a_time", "confirm", "record"):
quizme[name] = False
else:
quizme["enabled"] = True
quizme["multiple_choice"] = "--mc" in supported
quizme["one_at_a_time"] = "--one-at-a-time" in supported
quizme["record"] = "--record" in supported
quizme["confirm"] = "--confirm" in supported or quizme["record"]
notices.append(f"Quizme mode is {'on' if quizme['enabled'] else 'off'}.")
return "quizme-mode", True, notices, False
if command == "--internal-lang":
internal_lang = state["internal_lang"]
if len(arguments) == 1 and arguments[0] in {"on", "off"}:
internal_lang["internal"] = arguments[0] == "on"
notices.append(f"Internal compact notation is {arguments[0]}.")
elif len(arguments) == 2 and arguments[0] == "--response" and arguments[1] in {"on", "off"}:
internal_lang["response"] = arguments[1] == "on"
notices.append(f"Compact response notation is {arguments[1]}.")
else:
notices.append(
"Unsupported --internal-lang arguments; expected on|off or --response on|off."
)
return None, False, notices, False
return "internal-lang", True, notices, False
if command == "--ill-run-scripts":
if arguments:
notices.append("Unsupported --ill-run-scripts arguments; send the exact toggle command.")
return None, False, notices, False
state["user_run_scripts"] = not state["user_run_scripts"]
notices.append(f"User-run-scripts mode is {'on' if state['user_run_scripts'] else 'off'}.")
return "user-run-scripts", True, notices, False
return None, False, [f"Unknown command {command!r} was not consumed."], False
def process_event(payload: Mapping[str, Any]) -> dict[str, Any]:
"""Process one pack lifecycle or user-message event."""
if not isinstance(payload, Mapping):
raise RuntimeProtocolError("event payload must be an object")
_closed_keys(payload, {"schema_version", "event", "message", "state"}, "event payload")
if payload.get("schema_version") != SCHEMA_VERSION:
raise RuntimeProtocolError(f"event schema_version must equal {SCHEMA_VERSION}")
event = payload.get("event")
if event not in {"pack_loaded", "user_message"}:
raise RuntimeProtocolError("event must be 'pack_loaded' or 'user_message'")
if event == "pack_loaded" and "message" in payload:
raise RuntimeProtocolError("pack_loaded events must not contain message")
if event == "user_message" and not isinstance(payload.get("message"), str):
raise RuntimeProtocolError("user_message events require a string message")
persisted = _preference_state()
state = normalize_state(payload.get("state"))
for key in ("clean_slate", "quizme", "internal_lang", "user_run_scripts"):
state[key] = copy.deepcopy(persisted[key])
startup_messages: list[str] = []
if not state["startup_hint_emitted"]:
startup_messages.append(STARTUP_HINT)
state["startup_hint_emitted"] = True
command_skill: str | None = None
consumed = False
notices: list[str] = []
help_requested = False
source_sha256: str | None = None
if event == "user_message":
message = payload["message"]
source_sha256 = hashlib.sha256(message.encode("utf-8")).hexdigest()
command_skill, consumed, notices, help_requested = _parse_message(message, state)
if consumed and command_skill in {"clean-slate", "quizme-mode", "internal-lang", "user-run-scripts"}:
_persist_preferences(state)
return {
"schema_version": SCHEMA_VERSION,
"startup_messages": startup_messages,
"notices": notices,
"recognized_command": command_skill,
"consume_message": consumed,
"source_sha256": source_sha256,
"descriptor_patch": _descriptor_patch(state, command_skill, help_requested),
"descriptor_patch_policy": "deep_merge_with_explicit_skill_union",
"state": state,
}
def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"event_json",
nargs="?",
type=Path,
help="Event JSON file. Read stdin when omitted.",
)
return parser.parse_args(argv)
def main(argv: Sequence[str] | None = None) -> int:
args = parse_args(argv)
try:
raw = args.event_json.read_text(encoding="utf-8") if args.event_json else sys.stdin.read()
result = process_event(json.loads(raw))
except (OSError, json.JSONDecodeError, RuntimeProtocolError) as exc:
print(f"runtime adapter error: {exc}", file=sys.stderr)
return 2
print(json.dumps(result, indent=2, sort_keys=True))
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |