mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-21 16:46:26 +03:00

Files

T

Magnus Hedemarkandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> 83e07b9ac2 docs(peertube): thicken federated video skill against current API research

Research-driven rebuild of the peertube skill (docs.joinpeertube.org REST
reference 8.1.0 + SepiaSearch + server source + live anonymous probes):

- SKILL.md rewritten to the lastfm model: intent-grouped commands, pipeline
  recipes, jq guidance, researched gotchas, When-to-use/When-not-to-use,
  reference routing table. New negative boundary in the description
  (YouTube/Vimeo uploads, video editing, server administration).
- scripts/peertube-cli -> scripts/peertube, rewritten and extended:
  offset (start/count) pagination replaces the nonexistent page param,
  comments fixed to the hyphenated /comment-threads route, server command
  now composes /config/about + /server/stats (canonical paths), search
  gains --search-target with searchTarget=local default and help text
  stating its instance-local scope, new video/comments/channel/account/
  my-videos/logout commands, --server hoisted before or after the
  subcommand, OAuth2 password grant hardened for 2FA (x-peertube-otp)
  and the production client_secret masking behavior, per-instance
  owner-only token file with refresh-before-expiry and revocation.
- references/: auth-and-tokens, search-and-discovery, endpoint-catalog,
  gotchas-field-guide, worked-recipes - all cited to official docs with
  Sources footers (URLs verified live at authoring time).
- scripts/test_peertube.py: 54 offline tests (help, argument errors,
  dry-run plans, mocked OAuth2 persistence/refresh/revocation, handler
  contracts, documented pipeline chains) passing pytest strict-markers,
  unittest discovery, and the proxy-trap zero-egress rerun; one
  env-guarded anonymous live probe (PEERTUBE_LIVE_TESTS=1).
- evals/evals.json: six schema-v1 cases incl. SepiaSearch-scope and
  masked-secret cases plus a should-not-trigger YouTube negative probe.
- README refreshed for humans; root README blurb and skill-triggers row
  synced; marketplace.json/llms.txt regenerated (codex artifacts
  unchanged); test-results/ gitignored (pytest runner artifact).

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

2026-08-29 18:43:00 -04:00

3.7 KiB

Raw Blame History

PeerTube — Federated Video from the Terminal

Browse any PeerTube instance from the command line: latest videos, video detail, comment threads, channels and accounts, instance stats, and OAuth2 login for your own account — plus fediverse-wide search through SepiaSearch.

Why Install This Skill

When your agent loads this skill, it can navigate the federated video universe without a browser. That means:

Browse any instance — latest videos with real offset pagination (the API has no page parameter, and most naive wrappers get this wrong)
Search the right scope — instance-local search or the whole fediverse via SepiaSearch, with the searchTarget semantics documented instead of guessed
Inspect videos deeply — full metadata, comment threads (the hyphenated /comment-threads route), channels, and accounts by handle (name@host)
Check instance health — name, description, and user/video/view counters composed from /config/about + /server/stats anonymously
Authenticate safely — OAuth2 password grant with per-instance, owner-only token persistence, automatic refresh, and proper server-side revocation on logout
Avoid the traps — masked client_secret responses, token lifetimes that vary per instance, 2FA x-peertube-otp, rate-limit headers, RFC7807 error bodies

Every command is read-only except login/logout, and --dry-run previews any request without touching the network.

What You Get

Path	Purpose
`SKILL.md`	Complete command reference with setup, gotchas, and recipes
`scripts/peertube`	CLI for PeerTube API operations (`--json`, `--dry-run`, `--verbose`)
`scripts/test_peertube.py`	Offline test suite (all HTTP mocked, zero egress)
`references/auth-and-tokens.md`	The full OAuth2 flow, secret masking, token hygiene
`references/search-and-discovery.md`	Instance-local vs SepiaSearch search scopes
`references/endpoint-catalog.md`	Endpoint-by-endpoint parameters and response shapes
`references/gotchas-field-guide.md`	Failure signatures and version drift
`references/worked-recipes.md`	Multi-step CLI/jq and curl workflows
`evals/evals.json`	Behavioral eval cases including negative triggers

Quick Start

export PEERTUBE_SERVER="https://<INSTANCE_HOST>"   # any PeerTube instance
scripts/peertube server                            # instance stats, anonymous
scripts/peertube videos --limit 5 --json
scripts/peertube search --query "linux"            # searches THIS instance

Fediverse-wide search through SepiaSearch (same API shape, wider index):

PEERTUBE_SERVER="https://sepiasearch.org" scripts/peertube search --query "linux"

Optional login for your own account commands:

scripts/peertube login --username "<USERNAME>" --prompt
scripts/peertube me --json | jq '.role.label'
scripts/peertube logout                            # revokes server-side + deletes token file

Triggers

Load this when asking about PeerTube, federated video, decentralized video platforms, SepiaSearch, browsing a specific PeerTube instance's videos or channels, or PeerTube API authentication.

Requirements

Python 3.8+ with requests. One thing this skill always needs from you: an instance host — export PEERTUBE_SERVER (e.g. https://<INSTANCE_HOST>) or pass --server https://... per command, since PeerTube is federated and every command targets one instance. Reads are anonymous; me/my-videos need a token from scripts/peertube login. Tokens persist to ~/.config/peertube/token.json (override the directory with PEERTUBE_CONFIG_DIR). Find public instances at joinpeertube.org.

3.7 KiB Raw Blame History