FrancyJGLisboa/agent-skills-platform / .agents/skills/live-weather-briefing-skill
live-weather-briefing-skill
VerifiedCreate a current, source-linked weather briefing for a named city using the Open-Meteo geocoding and forecast APIs. Activate for requests such as "what is the weather in Sao Paulo?", "prepare a current weather briefing for Tokyo", or "get today's live conditions for New York". Do not use for travel booking, weather alerts, historical climatology, or safety-critical decisions.
| File | Kind | Size |
|---|---|---|
| .claude-plugin/marketplace.json | config | 378 B |
| .claude-plugin/plugin.json | config | 225 B |
| AGENTS.md | markdown | 664 B |
| EVOLUTION.md | markdown | 745 B |
| SKILL.md | skill md | 2.3 KB |
| discovery.json | config | 2.1 KB |
| evals/golden/new-york/input.txt | markdown | 13 B |
| evals/golden/sao-paulo/input.txt | markdown | 14 B |
| evals/golden/tokyo/input.txt | markdown | 10 B |
| evals/live-weather-briefing.eval.md | markdown | 1.4 KB |
| install.ps1 | script | 24.7 KB |
| interview.json | config | 5.6 KB |
| scripts/dependency_health.py | script | 3.9 KB |
| scripts/evolve.py | script | 10.2 KB |
| scripts/review_staleness.py | script | 6.2 KB |
| scripts/run_evals.py | script | 49.4 KB |
| scripts/run_pipeline.py | script | 4.7 KB |
| scripts/schema_drift.py | script | 7.3 KB |
| scripts/skill_document.py | script | 9.8 KB |
| scripts/staleness_check.py | script | 7.5 KB |
| scripts/success_ledger.py | script | 16.3 KB |
| skill.graph.json | config | 5.3 KB |
scripts/success_ledger.py
View on GitHub#!/usr/bin/env python3
"""Local lifecycle ledger and product-success metrics for generated skills.
The ledger is deliberately narrow: it stores fixed event names, timestamps,
pseudonymous skill IDs, run IDs, outcomes, and optional durations. It never
stores prompts, workflow descriptions, inputs, outputs, corrections, paths,
credentials, or network destinations, and it never transmits data.
"""
from __future__ import annotations
import argparse
import hashlib
import hmac
import json
import os
import secrets
import statistics
import sys
import time
import uuid
from collections import defaultdict
from datetime import datetime, timedelta, timezone
from pathlib import Path
SCHEMA_VERSION = 1
DISABLE_VALUE = "off"
ALLOWED_EVENTS = {
"creation_started",
"intent_confirmed",
"gates_passed",
"representative_run_passed",
"skill_run",
"correction_recorded",
"regression_detected",
"skill_shared",
}
RESULTS = {"success", "failure"}
SALT_FILE = ".success-ledger-salt"
SALT_SIZE = 32
SALT_LOCK_TIMEOUT_SECONDS = 5.0
def default_ledger_path() -> Path | None:
"""Return the local ledger path, or None when recording is disabled."""
configured = os.environ.get("ASC_SUCCESS_LEDGER")
if configured and configured.lower() == DISABLE_VALUE:
return None
if configured:
return Path(configured).expanduser()
state_root = os.environ.get("XDG_STATE_HOME")
if state_root:
return Path(state_root) / "agent-skills-platform" / "success-events.jsonl"
if os.name == "nt" and os.environ.get("LOCALAPPDATA"):
return Path(os.environ["LOCALAPPDATA"]) / "agent-skills-platform" / "success-events.jsonl"
return Path.home() / ".local" / "state" / "agent-skills-platform" / "success-events.jsonl"
def _salt(ledger_path: Path) -> bytes:
salt_path = ledger_path.parent / SALT_FILE
ledger_path.parent.mkdir(parents=True, exist_ok=True)
def read_valid_salt() -> bytes | None:
try:
value = salt_path.read_bytes()
except (FileNotFoundError, PermissionError):
return None
return value if len(value) == SALT_SIZE else None
existing = read_valid_salt()
if existing is not None:
return existing
lock_path = salt_path.with_name(f"{salt_path.name}.lock")
deadline = time.monotonic() + SALT_LOCK_TIMEOUT_SECONDS
while True:
try:
lock_descriptor = os.open(
lock_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600
)
except (FileExistsError, PermissionError):
# Windows can report a sharing violation as PermissionError while
# another thread owns an O_EXCL-created lock file.
existing = read_valid_salt()
if existing is not None:
return existing
if time.monotonic() >= deadline:
raise TimeoutError(f"timed out initializing privacy salt: {salt_path}")
time.sleep(0.01)
continue
os.close(lock_descriptor)
temporary_path = salt_path.with_name(
f"{salt_path.name}.{secrets.token_hex(8)}.tmp"
)
try:
existing = read_valid_salt()
if existing is None:
value = secrets.token_bytes(SALT_SIZE)
descriptor = os.open(
temporary_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600
)
try:
with os.fdopen(descriptor, "wb") as handle:
handle.write(value)
handle.flush()
os.fsync(handle.fileno())
except BaseException:
temporary_path.unlink(missing_ok=True)
raise
os.replace(temporary_path, salt_path)
try:
salt_path.chmod(0o600)
except OSError:
pass
return value
return existing
finally:
temporary_path.unlink(missing_ok=True)
lock_path.unlink(missing_ok=True)
def _skill_id(skill: str, ledger_path: Path) -> str:
normalized = skill.strip()
if not normalized:
raise ValueError("skill identifier is empty")
return hmac.new(_salt(ledger_path), normalized.encode("utf-8"), hashlib.sha256).hexdigest()[:20]
def _append_line(destination: Path, line: str) -> None:
lock_path = destination.with_name(f"{destination.name}.lock")
deadline = time.monotonic() + SALT_LOCK_TIMEOUT_SECONDS
while True:
try:
descriptor = os.open(
lock_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600
)
except FileExistsError:
if time.monotonic() >= deadline:
raise TimeoutError(f"timed out appending to success ledger: {destination}")
time.sleep(0.01)
continue
os.close(descriptor)
break
try:
with destination.open("a", encoding="utf-8") as handle:
handle.write(line)
handle.flush()
os.fsync(handle.fileno())
finally:
lock_path.unlink(missing_ok=True)
def _timestamp(value: datetime | None) -> datetime:
stamp = value or datetime.now(timezone.utc)
if stamp.tzinfo is None:
raise ValueError("timestamp must include a timezone")
return stamp.astimezone(timezone.utc)
def _iso(value: datetime) -> str:
return value.isoformat(timespec="seconds").replace("+00:00", "Z")
def record_event(
event: str,
*,
skill: str,
ledger_path: str | Path | None = None,
timestamp: datetime | None = None,
run_id: str | None = None,
result: str = "success",
duration_seconds: float | None = None,
) -> dict | None:
"""Append one allowlisted event without storing the skill's name or content."""
if event not in ALLOWED_EVENTS:
raise ValueError(f"unknown event: {event}")
if result not in RESULTS:
raise ValueError(f"result must be one of: {', '.join(sorted(RESULTS))}")
if duration_seconds is not None and duration_seconds < 0:
raise ValueError("duration_seconds must be non-negative")
destination = Path(ledger_path) if ledger_path is not None else default_ledger_path()
if destination is None:
return None
if run_id is not None:
try:
normalized_run_id = str(uuid.UUID(run_id))
except ValueError as exc:
raise ValueError("run_id must be a UUID from the new-run command") from exc
else:
normalized_run_id = str(uuid.uuid4())
item = {
"schema_version": SCHEMA_VERSION,
"event": event,
"skill_id": _skill_id(skill, destination),
"timestamp": _iso(_timestamp(timestamp)),
"run_id": normalized_run_id,
"result": result,
"duration_seconds": duration_seconds,
}
destination.parent.mkdir(parents=True, exist_ok=True)
_append_line(
destination, json.dumps(item, separators=(",", ":"), sort_keys=True) + "\n"
)
try:
destination.chmod(0o600)
except OSError:
pass
return item
def _parse_stamp(value: str) -> datetime:
return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
def _read_events(ledger_path: Path, as_of: datetime) -> tuple[list[dict], int]:
events: list[dict] = []
malformed = 0
if not ledger_path.exists():
return events, malformed
for line in ledger_path.read_text(encoding="utf-8").splitlines():
try:
item = json.loads(line)
stamp = _parse_stamp(item["timestamp"])
if item["event"] not in ALLOWED_EVENTS or item["result"] not in RESULTS:
raise ValueError("invalid vocabulary")
except (KeyError, TypeError, ValueError, json.JSONDecodeError):
malformed += 1
continue
if stamp <= as_of:
events.append({**item, "_stamp": stamp})
events.sort(key=lambda item: item["_stamp"])
return events, malformed
def _rate(numerator: int, denominator: int) -> float | None:
return round(numerator / denominator, 4) if denominator else None
def summarize(
ledger_path: str | Path,
*,
as_of: datetime | None = None,
active_window_days: int = 28,
second_run_days: int = 14,
) -> dict:
"""Compute activation, retention, quality, and distribution metrics."""
now = _timestamp(as_of)
if active_window_days < 1 or second_run_days < 1:
raise ValueError("metric windows must be positive")
events, malformed = _read_events(Path(ledger_path), now)
by_skill: dict[str, list[dict]] = defaultdict(list)
by_run: dict[str, list[dict]] = defaultdict(list)
for event in events:
by_skill[event["skill_id"]].append(event)
by_run[event["run_id"]].append(event)
starts = [event for event in events if event["event"] == "creation_started"]
verified: list[tuple[dict, dict]] = []
for start in starts:
completions = [
event
for event in by_run[start["run_id"]]
if event["event"] == "representative_run_passed"
and event["result"] == "success"
and event["_stamp"] >= start["_stamp"]
]
if completions:
verified.append((start, completions[0]))
minutes = [
(completion["_stamp"] - start["_stamp"]).total_seconds() / 60
for start, completion in verified
]
eligible_second_runs = [
pair for pair in verified if pair[1]["_stamp"] <= now - timedelta(days=second_run_days)
]
returned = 0
for _, completion in eligible_second_runs:
deadline = completion["_stamp"] + timedelta(days=second_run_days)
if any(
event["event"] == "skill_run"
and event["result"] == "success"
and completion["_stamp"] < event["_stamp"] <= deadline
for event in by_skill[completion["skill_id"]]
):
returned += 1
active_since = now - timedelta(days=active_window_days)
durable: set[str] = set()
for skill_id, skill_events in by_skill.items():
successful_runs = [
event
for event in skill_events
if event["event"] in {"representative_run_passed", "skill_run"}
and event["result"] == "success"
and event["_stamp"] >= active_since
]
last_gate = max(
(
event["_stamp"]
for event in skill_events
if event["event"] == "gates_passed" and event["result"] == "success"
),
default=None,
)
last_regression = max(
(event["_stamp"] for event in skill_events if event["event"] == "regression_detected"),
default=None,
)
regression_resolved = last_regression is None or (
last_gate is not None and last_gate > last_regression
)
if (
len(successful_runs) >= 3
and len({event["_stamp"].date() for event in successful_runs}) >= 2
and last_gate is not None
and regression_resolved
):
durable.add(skill_id)
corrections = [event for event in events if event["event"] == "correction_recorded"]
recovered = 0
for correction in corrections:
later = [
event
for event in by_skill[correction["skill_id"]]
if event["_stamp"] > correction["_stamp"]
]
latest_gate = max(
(
event["_stamp"]
for event in later
if event["event"] == "gates_passed" and event["result"] == "success"
),
default=None,
)
latest_regression = max(
(event["_stamp"] for event in later if event["event"] == "regression_detected"),
default=None,
)
if latest_gate is not None and (
latest_regression is None or latest_gate > latest_regression
):
recovered += 1
shared_durable = sum(
any(
event["event"] == "skill_shared" and event["result"] == "success"
for event in by_skill[skill_id]
)
for skill_id in durable
)
return {
"as_of": _iso(now),
"active_window_days": active_window_days,
"second_run_window_days": second_run_days,
"counts": {
"events": len(events),
"malformed_events_skipped": malformed,
"creations_started": len(starts),
"verified_creations": len(verified),
"eligible_for_second_run": len(eligible_second_runs),
"corrections": len(corrections),
},
"verified_creation_rate": _rate(len(verified), len(starts)),
"median_minutes_to_first_result": round(statistics.median(minutes), 2) if minutes else None,
"fourteen_day_second_run_rate": _rate(returned, len(eligible_second_runs)),
"durable_active_skills": len(durable),
"correction_recovery_rate": _rate(recovered, len(corrections)),
"shared_durable_skill_rate": _rate(shared_durable, len(durable)),
}
def _print_summary(summary: dict) -> None:
def percentage(value: float | None) -> str:
return "n/a" if value is None else f"{value * 100:.1f}%"
print(f"Durable active skills: {summary['durable_active_skills']}")
print(f"Verified creation rate: {percentage(summary['verified_creation_rate'])}")
median = summary["median_minutes_to_first_result"]
print(f"Median to first result: {'n/a' if median is None else f'{median:.1f} min'}")
print(f"14-day second-run rate: {percentage(summary['fourteen_day_second_run_rate'])}")
print(f"Correction recovery rate: {percentage(summary['correction_recovery_rate'])}")
print(f"Shared durable-skill rate: {percentage(summary['shared_durable_skill_rate'])}")
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Record local skill lifecycle events and summarize product success.")
parser.add_argument("--ledger", help="Override the local JSONL ledger path.")
subparsers = parser.add_subparsers(dest="command", required=True)
record = subparsers.add_parser("record")
record.add_argument("event", choices=sorted(ALLOWED_EVENTS))
record.add_argument("--skill", required=True, help="Hashed locally; never written in plaintext.")
record.add_argument("--run-id")
record.add_argument("--result", choices=sorted(RESULTS), default="success")
record.add_argument("--duration-seconds", type=float)
summary_parser = subparsers.add_parser("summary")
summary_parser.add_argument("--json", action="store_true")
summary_parser.add_argument("--as-of", help="ISO-8601 timestamp for reproducible reports.")
summary_parser.add_argument("--active-window-days", type=int, default=28)
summary_parser.add_argument("--second-run-days", type=int, default=14)
subparsers.add_parser("path")
subparsers.add_parser("new-run")
args = parser.parse_args(argv)
destination = Path(args.ledger) if args.ledger else default_ledger_path()
if args.command == "new-run":
print(uuid.uuid4())
return 0
if args.command == "path":
print("disabled" if destination is None else destination)
return 0
if args.command == "record":
try:
item = record_event(
args.event,
skill=args.skill,
ledger_path=destination,
run_id=args.run_id,
result=args.result,
duration_seconds=args.duration_seconds,
)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
print("recording disabled" if item is None else f"recorded {item['event']} for {item['skill_id']}")
return 0
if destination is None:
print("error: recording is disabled; set ASC_SUCCESS_LEDGER to a local path", file=sys.stderr)
return 2
try:
as_of = _parse_stamp(args.as_of) if args.as_of else None
report = summarize(
destination,
as_of=as_of,
active_window_days=args.active_window_days,
second_run_days=args.second_run_days,
)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if args.json:
print(json.dumps(report, indent=2))
else:
_print_summary(report)
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: 472k | Updated | Claude CodeCodex | Unverified | 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 |