FrancyJGLisboa/agent-skills-platform / references/examples/github-release-briefing-skill
github-release-briefing-skill
UnverifiedCreate a source-linked briefing for the latest published GitHub release of a public repository. Use for engineering teams tracking a dependency release; do not use it to publish releases or change repositories.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 245 B |
| README.md | markdown | 223 B |
| SKILL.md | skill md | 1.9 KB |
| VERIFICATION.md | markdown | 864 B |
| contracts/data_contract_github_releases/.contract_id | other | 16 B |
| contracts/data_contract_github_releases/code/contract_health.py | script | 355 B |
| discovery.json | config | 2.7 KB |
| evals/caliper/github-release-briefing-skill.eval.yaml | config | 2.8 KB |
| evals/github-release-briefing.eval.md | markdown | 1.3 KB |
| evals/golden/anthropic-sdk-python/input.txt | markdown | 32 B |
| evals/golden/flask/input.txt | markdown | 14 B |
| evals/golden/openai-python/input.txt | markdown | 21 B |
| evals/golden/requests/input.txt | markdown | 13 B |
| evals/golden/vercel-ai/input.txt | markdown | 10 B |
| 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 | 2.6 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.5 KB |
scripts/review_staleness.py
View on GitHub#!/usr/bin/env python3
"""
Review staleness check for a skill.
Compares `metadata.last_reviewed` against `metadata.review_interval_days`. Falls
back to the git commit date for SKILL.md when explicit review dates are absent.
No network. Pure date math + a single git subprocess call.
"""
from __future__ import annotations
import re
import subprocess
from datetime import date, timedelta
from pathlib import Path
from skill_document import SkillDoc
DEFAULT_REVIEW_INTERVAL_DAYS = 90
STALENESS_WARNING_THRESHOLD_DAYS = 60
_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
def _parse_date(value: str) -> date | None:
"""Parse a YYYY-MM-DD string into a date object, or None on failure."""
if not value or not _DATE_RE.match(value.strip()):
return None
try:
y, m, d = value.strip().split("-")
return date(int(y), int(m), int(d))
except (ValueError, IndexError):
return None
def get_git_last_modified(skill_path: str) -> date | None:
"""Return the date of the last git commit touching SKILL.md, or None if
git is unavailable, the file is untracked, or the call times out."""
skill_md = Path(skill_path).resolve() / "SKILL.md"
if not skill_md.exists():
return None
try:
result = subprocess.run(
["git", "log", "-1", "--format=%aI", "--", str(skill_md)],
capture_output=True,
text=True,
timeout=10,
cwd=str(Path(skill_path).resolve()),
)
if result.returncode != 0 or not result.stdout.strip():
return None
return _parse_date(result.stdout.strip()[:10]) # ISO "YYYY-MM-DDTHH:..." -> "YYYY-MM-DD"
except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
return None
def classify_staleness(
reference_date: date,
interval_days: int,
today: date,
) -> tuple[str, int, date]:
"""Single source of truth for review-staleness status.
Returns (status, days_since, deadline) where status is "overdue",
"due_soon", or "fresh". Used by both the per-skill check below and the
registry-wide `stale` report in skill_registry.py.
"""
days_since = (today - reference_date).days
deadline = reference_date + timedelta(days=interval_days)
if today > deadline:
return "overdue", days_since, deadline
if today > reference_date + timedelta(days=STALENESS_WARNING_THRESHOLD_DAYS):
return "due_soon", days_since, deadline
return "fresh", days_since, deadline
def check_review_staleness(
doc: SkillDoc,
git_last_modified: date | None,
today: date | None = None,
) -> tuple[list[dict], str, int | None, str]:
"""
Decide whether the skill is overdue for review.
`today` is injectable for tests. Returns (issues, review_status,
days_since_review, date_source). review_status is one of "fresh",
"due_soon", "overdue", or "unknown".
"""
if today is None:
today = date.today()
issues: list[dict] = []
created_str = doc.subfield("metadata", "created")
last_reviewed_str = doc.subfield("metadata", "last_reviewed")
interval_str = doc.subfield("metadata", "review_interval_days")
# Validate formats (warnings only)
if created_str and not _parse_date(created_str):
issues.append({
"level": "warning",
"message": "Invalid 'metadata.created' date format",
"detail": f"Expected YYYY-MM-DD, got: '{created_str}'",
})
if last_reviewed_str and not _parse_date(last_reviewed_str):
issues.append({
"level": "warning",
"message": "Invalid 'metadata.last_reviewed' date format",
"detail": f"Expected YYYY-MM-DD, got: '{last_reviewed_str}'",
})
if interval_str:
try:
int(interval_str)
except ValueError:
issues.append({
"level": "warning",
"message": "Invalid 'metadata.review_interval_days' value",
"detail": f"Expected integer, got: '{interval_str}'",
})
interval_days = DEFAULT_REVIEW_INTERVAL_DAYS
if interval_str:
try:
interval_days = int(interval_str)
except ValueError:
pass
reference_date: date | None = None
date_source = "unknown"
last_reviewed = _parse_date(last_reviewed_str) if last_reviewed_str else None
if last_reviewed:
reference_date = last_reviewed
date_source = "last_reviewed"
elif git_last_modified:
reference_date = git_last_modified
date_source = "git_commit"
else:
issues.append({
"level": "info",
"message": "No review date available",
"detail": "No 'metadata.last_reviewed' and no git history found. "
"Consider adding temporal metadata.",
})
days_since: int | None = None
review_status = "unknown"
if reference_date:
review_status, days_since, deadline = classify_staleness(
reference_date, interval_days, today
)
if review_status == "overdue":
issues.append({
"level": "error",
"message": f"Skill is overdue for review ({days_since} days since last review)",
"detail": f"Review interval is {interval_days} days. "
f"Last review: {reference_date} (source: {date_source}). "
f"Deadline was: {deadline}.",
})
elif review_status == "due_soon":
days_remaining = (deadline - today).days
issues.append({
"level": "warning",
"message": f"Review due in {days_remaining} days",
"detail": f"Last review: {reference_date} (source: {date_source}). "
f"Deadline: {deadline}.",
})
has_any_temporal = bool(created_str or last_reviewed_str or interval_str)
if not has_any_temporal:
issues.append({
"level": "info",
"message": "No temporal metadata found",
"detail": "Consider adding metadata.created, metadata.last_reviewed, "
"and metadata.review_interval_days to frontmatter.",
})
return issues, review_status, days_since, date_source
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 |