agentleFS
8TrafficAI8TrafficAI/youtube-skills/skills/youtube-shorts-publish/SKILL.md

youtube-shorts-publish

Skill0 starsChanged 3 months agoMITView on GitHub

Inspect, plan, authenticate, upload, schedule, and verify YouTube Shorts through the official YouTube Data API, for the user's own channel. Use whenever someone asks to upload, publish, post, or schedule a YouTube Short; check whether a video qualifies as a Short; safely dry-run a YouTube upload; configure YouTube upload OAuth; diagnose a Short stuck processing, rejected, or unexpectedly private; or verify an upload by video ID. Handles local ffprobe media checks, Desktop OAuth, private-by-default resumable uploads, Made for Kids and synthetic-media declarations, and post-upload processing checks. Not for generating or editing the video, bulk multi-channel posting, evading platform enforcement, or claiming Shorts Feed placement that the API cannot prove.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. 8TrafficAI/8traffic-marketing-skills★ 0100% same

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 7 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the bundled zero-dependency Node CLI.

    line 17
  2. Very specific:

    Run a dry plan before every upload.

    line 24
  3. Very specific:

    Only add --yes and the reviewed --expected-plan-id when the user's request clearly authorizes that exact upload and the plan's channel, …

    line 26
  4. Very specific:

    Keep the default private unless the user explicitly asks for public, unlisted, or a future publication time.

    line 29
  5. Very specific:

    Never infer whether content is Made for Kids or contains realistic altered/synthetic media.

    line 31
  6. Very specific:

    Use the channel ID returned by auth.

    line 33
  7. Very specific:

    Treat a plan_id as one-shot.

    line 34
  8. Distinctive:

    After an upload returns an ID, check that ID.

    line 37
  9. Distinctive:

    Call an eligible upload a Shorts candidate.

    line 39
  10. Very specific:

    Run node examples/verify-zero-publish.mjs with no arguments.

    line 56
  11. Very specific:

    Treat passed: true only as a deterministic installation and safety-contract check.

    line 62
  12. Distinctive:

    After an independent installed-copy run, use the structured zero-publish tester form.

    line 66
  13. Distinctive:

    Read OAuth setup, then run:

    line 76
  14. Very specific:

    Treat shorts_candidate: true as a local check against the published duration and displayed aspect rules.

    line 94
  15. Distinctive:

    If the video needs conversion, let the user choose crop versus padding and then consult media preparation.

    line 99
  16. Very specific:

    If public or unlisted was requested but read-back says private, report privacy_restricted and explain that an unaudited API project is a …

    line 190
  17. Distinctive:

    Do not expose OAuth codes, bearer/refresh tokens, client secrets, or resumable session URLs in chat, logs, commits, or issue reports.

    line 216

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Publish YouTube Shorts safely

Use the bundled zero-dependency Node CLI. It separates local eligibility, API acceptance, video processing, visibility, and Shorts classification instead of treating them as one success state.

Non-negotiable safety rules

  • Work with one channel owned or controlled by the user. Never rotate accounts, proxies, or OAuth clients to evade quotas or enforcement.
  • Run a dry plan before every upload. plan never reads OAuth files, contacts Google, or writes local state. publish without --yes has the same guarantee.
  • Only add --yes and the reviewed --expected-plan-id when the user's request clearly authorizes that exact upload and the plan's channel, source SHA-256, title, visibility, schedule, and declarations match their intent.
  • Keep the default private unless the user explicitly asks for public, unlisted, or a future publication time. Scheduling a private video means it will become public later.
  • Never infer whether content is Made for Kids or contains realistic altered/synthetic media. Obtain explicit yes or no choices for both.
  • Use the channel ID returned by auth; the CLI refuses a write if the authorized channel differs.
  • Treat a plan_id as one-shot. Before creating an upload session, the CLI stores a receipt and a read-only snapshot matching the reviewed SHA-256. A previous receipt blocks the same plan by default, including after crashes and ambiguous responses.
  • After an upload returns an ID, check that ID. Never search by title, delete a same-title video, or blindly upload again because processing or verification timed out.
  • Call an eligible upload a Shorts candidate. The Data API has no Shorts classification field, so do not claim confirmed Shorts Feed placement.

Locate the CLI

Commands below assume the current directory is this skill directory. Otherwise use the absolute path to scripts/ytshorts.mjs. Pass an absolute path for the source video when changing directories.

node scripts/ytshorts.mjs --help
node scripts/ytshorts.mjs doctor

Requirements are Node.js 20+ and ffprobe. There are no npm runtime dependencies.

Verify the installed contract without YouTube

Run node examples/verify-zero-publish.mjs with no arguments. It generates and removes a local one-second portrait fixture, then exercises only inspect and plan. It does not run auth, status, publish, or --yes; it points OAuth paths at absent sentinels and runs both CLI commands under a network guard that first passes a deliberately blocked canary. Return its compact stdout unchanged when the user asks for the evaluation result.

Treat passed: true only as a deterministic installation and safety-contract check. It does not prove that a real upload will succeed or that YouTube will place media in the Shorts Feed. The verifier requires ffmpeg as well as ffprobe; both are provided by FFmpeg.

After an independent installed-copy run, use the structured zero-publish tester form. Choose completed only if the reporter independently installed and actually ran youtube-shorts-publish for their own non-internal purpose and is not a maintainer, a maintainer's teammate, or an internal tester. Use the incomplete outcome when the exact no-argument verifier did not finish, and never include OAuth data, tokens, client secrets, authorization codes, resumable URLs, a real channel ID, or personal paths. This is installation and safety-contract evidence, not proof of a live upload or Shorts Feed placement.

First-time authorization

Read OAuth setup, then run:

node scripts/ytshorts.mjs auth

The system browser handles Google consent through a Desktop-app loopback flow. It requests youtube.upload for insertion and youtube.readonly for the channel guard and owner-only status read-back. Record the returned channel_id; pass it to every plan and publish command. Never open or print the token file. If authorization is not needed for the current task, do not run auth speculatively.

Inspect local media

node scripts/ytshorts.mjs inspect /absolute/path/short.mp4

Treat shorts_candidate: true as a local check against the published duration and displayed aspect rules. Rotation and sample aspect ratio are applied before deciding whether the video is square or vertical. A missing audio track is only a warning. Landscape media, unknown duration, or duration over 180 seconds blocks publishing.

If the video needs conversion, let the user choose crop versus padding and then consult media preparation. Do not silently alter their composition.

Build an exact, side-effect-free plan

node scripts/ytshorts.mjs plan /absolute/path/short.mp4 \
  --title "Launch day in 30 seconds" \
  --description-file /absolute/path/description.txt \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --privacy private \
  --made-for-kids no \
  --contains-synthetic-media no

Useful metadata flags:

  • --tag value is repeatable; comma-separated values also work.
  • --category-id 22 defaults to People & Blogs.
  • --notify-subscribers yes|no defaults to no.
  • --default-language en sets the metadata language.
  • --publish-at 2026-08-10T09:00:00+08:00 requires --privacy private and represents future public visibility. It must remain at least 30 minutes away throughout session creation and chunk transfer; otherwise the CLI stops rather than risk a past timestamp becoming public immediately.

Inspect safe_to_publish, blocking_issues, warnings, target, source sha256, plan_id, and the exact API request (including notifySubscribers). Resolve every blocker before proceeding. The channel is verified online only after confirmation; the plan marks that explicitly.

Publish only after reviewing the plan

The same command without --yes is still a dry run:

node scripts/ytshorts.mjs publish /absolute/path/short.mp4 \
  --title "Launch day in 30 seconds" \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --privacy private \
  --made-for-kids no \
  --contains-synthetic-media no

For a user-authorized real upload, repeat the unchanged command with the dry run's plan_id and --yes:

node scripts/ytshorts.mjs publish /absolute/path/short.mp4 \
  --title "Launch day in 30 seconds" \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --privacy private \
  --made-for-kids no \
  --contains-synthetic-media no \
  --expected-plan-id PLAN_ID_FROM_DRY_RUN \
  --yes

The CLI hashes the video and canonical request again before touching OAuth. A changed video, description file, metadata flag, or target produces PLAN_CHANGED and no upload starts. After the channel check it copies those reviewed bytes to a 0400 local snapshot and atomically creates an operation receipt immediately before mutation.

The uploader creates one resumable session, sends fixed 8 MiB chunks, follows YouTube's 308 Range offset after interruptions, renews OAuth access before expiry without restarting the session, and polls the returned video ID for up to 60 seconds by default. Set --wait-seconds 0..900 to change that window. Progress goes to stderr; structured results go to stdout.

One plan_id gets one upload attempt by default. Receipts live under the configured operations/ directory and contain no OAuth token or resumable session URL. If a prior attempt is ambiguous, inspect its receipt and YouTube Studio. Only after confirming no video exists may the user explicitly authorize the same command with --new-attempt; never add that flag automatically. The CLI permits at most one such exceptional retry and refuses it when any prior receipt already contains a video ID. It also requires the primary receipt itself to say ambiguous; a preparing or active-looking receipt is fail-closed so a second process cannot upload concurrently.

Interpret and recheck the result

statemeaningnext action
uploaded_processingbytes arrived; YouTube is still processingwait, then run status; do not re-upload
processed_privateprocessing succeeded; actual visibility is privatereview metadata or publish manually when intended
processed_unlisted / processed_publicprocessing and requested visibility succeededreport success, still as a Shorts candidate
processed_scheduledprocessing succeeded and future public release remains scheduledreport the schedule and preserve private-until-publish state
processing_failed / rejectedYouTube failed or rejected the videoreport the returned reason; fix before a new upload
verification_timeouta video ID exists, but the wait window endedrun status VIDEO_ID; do not re-upload
not_found_after_insertID returned but read-back is not visible yetpreserve the ID and recheck; treat outcome as unresolved
node scripts/ytshorts.mjs status VIDEO_ID
node scripts/ytshorts.mjs status VIDEO_ID --wait-seconds 120

If public or unlisted was requested but read-back says private, report privacy_restricted and explain that an unaudited API project is a common cause. Do not auto-update visibility. Read YouTube API and Shorts behavior before diagnosing policy, quota, Content ID, scheduling, or classification behavior.

For publish, top-level upload_accepted: true means YouTube returned a video ID. Top-level ok: true requires semantic verification too. A false ok with a video ID is not permission to retry; follow verification.state and the receipt.

Troubleshooting

symptomlikely causeresponse
FFPROBE_NOT_FOUNDffprobe is not installed or not on PATHinstall FFmpeg or set YTSHORTS_FFPROBE_BIN
CLIENT_SECRETS_NOT_FOUNDDesktop OAuth JSON is not configuredfollow references/oauth-setup.md
OAUTH_REAUTH_REQUIREDtoken revoked/expired; Testing projects often expire it after 7 daysrun auth again; review consent-screen publishing status
OAUTH_REFRESH_TOKEN_REQUIREDstored authorization cannot renew during a long uploadrun auth again; do not substitute a short-lived access token
CHANNEL_MISMATCHGoogle authorized a different channelstop; authorize/select the intended channel or correct --channel-id
PLAN_CHANGEDsource bytes or normalized request differ from the reviewed dry runinspect the new plan; never reuse the old ID
PLAN_ALREADY_ATTEMPTEDthis exact plan already has a durable receiptinspect the receipt and Studio; default is never retry
PLAN_VIDEO_ALREADY_EXISTSa prior receipt already records a YouTube video IDcheck that video; this plan is permanently ineligible for retry
PRIOR_ATTEMPT_NOT_AMBIGUOUSthe prior receipt is preparing, active-looking, or completeddo not override it; this prevents concurrent duplicate uploads
UPLOAD_OUTCOME_AMBIGUOUSa session started but completion could not be provendo not repeat; inspect Studio, then require explicit user approval for --new-attempt if absent
requested public, actual privateAPI project may require a YouTube compliance auditkeep the video private and follow Google's audit path
state remains processingnormal asynchronous transcode or an eventual processing issuere-run status; never duplicate the upload

Do not expose OAuth codes, bearer/refresh tokens, client secrets, or resumable session URLs in chat, logs, commits, or issue reports.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.