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/skill_document.py
View on GitHub#!/usr/bin/env python3
"""
Skill-document parsing for agent-skills-platform.
`SkillDoc` is the single source of SKILL.md parsing. It owns frontmatter
extraction and the deliberately-simple YAML reads (scalar fields, parent.child
sub-fields, and lists-of-objects) that validate.py, staleness_check.py,
skill_registry.py, and export_utils.py all need. Parse once via `from_text` /
`from_path`, then query through the interface. Validation *rules* (length
limits, name regex, link checks) stay in validate.py — this module only parses.
The YAML reads are intentionally not a full YAML parser: they match the narrow
shapes the spec uses and avoid a PyYAML dependency.
"""
from __future__ import annotations
from pathlib import Path
_BLOCK_SCALAR_INDICATORS = (">-", "|-", ">", "|", ">+", "|+")
def _split_frontmatter(content: str) -> tuple[str | None, str | None]:
"""Return (frontmatter, body) or (None, None) if frontmatter is absent or
not closed."""
if not content.startswith("---"):
return None, None
closing_index = content.find("---", 3)
if closing_index == -1:
return None, None
frontmatter = content[3:closing_index].strip()
body = content[closing_index + 3:].strip()
return frontmatter, body
class SkillDoc:
"""Parsed view of a SKILL.md document."""
def __init__(self, frontmatter: str | None, body: str | None) -> None:
self._frontmatter = frontmatter
self._body = body
@classmethod
def from_text(cls, content: str) -> SkillDoc:
"""Parse SKILL.md content. `frontmatter`/`body` are None when absent."""
frontmatter, body = _split_frontmatter(content)
return cls(frontmatter, body)
@classmethod
def from_path(cls, path: str | Path) -> SkillDoc:
"""Parse a SKILL.md file from disk."""
content = Path(path).read_text(encoding="utf-8")
return cls.from_text(content)
# --- Raw sections ---
@property
def frontmatter(self) -> str | None:
return self._frontmatter
@property
def body(self) -> str | None:
return self._body
# --- Typed accessors for the universal fields ---
@property
def name(self) -> str | None:
return self.field("name")
@property
def description(self) -> str | None:
return self.field("description")
@property
def license(self) -> str | None:
return self.field("license")
@property
def metadata(self) -> dict[str, str]:
"""Direct scalar children of the `metadata:` block (non-empty values).
Nested structures (e.g. `dependencies:`) are excluded; read those with
`list_of_objects`. Only the first child-indent level is collected — use
`subfield()` if you need an any-depth lookup.
"""
return self._collect_scalar_children("metadata")
# --- Generic queries ---
def field(self, field: str) -> str | None:
"""Top-level scalar field value, joining a YAML block scalar if used."""
if self._frontmatter is None:
return None
lines = self._frontmatter.split("\n")
for i, line in enumerate(lines):
if line[:1] in (" ", "\t"):
continue # indented lines are nested keys, not top-level fields
stripped = line.strip()
if stripped.startswith(f"{field}:"):
value = stripped[len(field) + 1:].strip()
if value in _BLOCK_SCALAR_INDICATORS:
parts: list[str] = []
for j in range(i + 1, len(lines)):
continuation = lines[j]
if continuation and (continuation[0] == " " or continuation[0] == "\t"):
parts.append(continuation.strip())
else:
break
return " ".join(parts) if parts else ""
return value
return None
def has_field(self, field: str) -> bool:
"""True if `field` appears as a top-level key."""
if self._frontmatter is None:
return False
for line in self._frontmatter.split("\n"):
if line[:1] in (" ", "\t"):
continue
if line.strip().startswith(f"{field}:"):
return True
return False
def subfield(self, parent: str, child: str) -> str | None:
"""Scalar value of `child` as a DIRECT child of the top-level `parent:` block.
Deeper-nested keys with the same name (e.g. a `version:` inside a
`dependencies:` list item) are ignored.
"""
if self._frontmatter is None:
return None
in_parent = False
child_indent: int | None = None
for line in self._frontmatter.split("\n"):
stripped = line.strip()
if not in_parent:
if line[:1] not in (" ", "\t") and stripped.startswith(f"{parent}:"):
in_parent = True
continue
if not stripped:
continue # blank lines don't end the block
indent = len(line) - len(line.lstrip())
if indent == 0:
break
if child_indent is None:
child_indent = indent
if indent == child_indent and stripped.startswith(f"{child}:"):
return stripped[len(child) + 1:].strip()
return None
def has_subfield(self, parent: str, child: str) -> bool:
"""True if `child` exists as a direct child of the top-level `parent:` block."""
return self.subfield(parent, child) is not None
def list_of_objects(self, parent: str, child: str) -> list[dict]:
"""Parse a YAML list-of-objects under `parent.child`.
Handles::
metadata:
dependencies:
- url: https://example.com
name: Example
type: api
"""
if self._frontmatter is None:
return []
lines = self._frontmatter.split("\n")
items: list[dict] = []
in_parent = False
in_child = False
current_item: dict | None = None
child_indent = -1
for line in lines:
stripped = line.strip()
if not in_parent:
if stripped.startswith(f"{parent}:"):
in_parent = True
continue
if line and line[0] != " " and line[0] != "\t" and stripped:
break
if not in_child:
if stripped.startswith(f"{child}:"):
in_child = True
continue
if not stripped:
continue
raw_indent = len(line) - len(line.lstrip())
if child_indent == -1 and stripped.startswith("- "):
child_indent = raw_indent
if raw_indent <= child_indent and not stripped.startswith("- "):
if ":" in stripped:
break
if stripped.startswith("- "):
if current_item is not None:
items.append(current_item)
current_item = {}
rest = stripped[2:].strip()
if ":" in rest:
key, _, val = rest.partition(":")
current_item[key.strip()] = val.strip()
elif current_item is not None and ":" in stripped:
key, _, val = stripped.partition(":")
current_item[key.strip()] = val.strip()
if current_item is not None:
items.append(current_item)
return items
def list_of_scalars(self, parent: str, child: str) -> list[str]:
"""Parse a YAML block list of scalar values under ``parent.child``."""
if self._frontmatter is None:
return []
lines = self._frontmatter.split("\n")
in_parent = False
in_child = False
child_indent: int | None = None
values: list[str] = []
for line in lines:
stripped = line.strip()
indent = len(line) - len(line.lstrip())
if not in_parent:
if indent == 0 and stripped == f"{parent}:":
in_parent = True
continue
if indent == 0 and stripped:
break
if not in_child:
if stripped == f"{child}:":
in_child = True
child_indent = indent
continue
if not stripped:
continue
if child_indent is not None and indent <= child_indent:
break
if not stripped.startswith("- "):
break
value = stripped[2:].strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
value = value[1:-1]
if value:
values.append(value)
return values
def _collect_scalar_children(self, parent: str) -> dict[str, str]:
"""All direct scalar children of `parent:` with non-empty inline values."""
if self._frontmatter is None:
return {}
result: dict[str, str] = {}
in_parent = False
child_indent: int | None = None
for line in self._frontmatter.split("\n"):
stripped = line.strip()
if not in_parent:
if stripped.startswith(f"{parent}:"):
in_parent = True
continue
if not stripped:
continue
indent = len(line) - len(line.lstrip())
if indent == 0:
break
if child_indent is None:
child_indent = indent
if indent == child_indent and ":" in stripped and not stripped.startswith("- "):
key, _, val = stripped.partition(":")
val = val.strip()
if val:
result[key.strip()] = val
return result
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: 470k | 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 |