Agent-Skills.md

Agent Skills: SourceCraft Publisher

Publish static page artifacts to SourceCraft Sites (Yandex infrastructure, works in Russia), with advisory image optimization and an original-image path. Use when a static page/React artifact needs to be deployed to SourceCraft under YYYY/YYYY-MM/page-slug directory layout.

UncategorizedID: artwist-polyakov/polyakov-claude-skills/sourcecraft-publisher

Repository

artwist-polyakov/polyakov-claude-skills
artwist-polyakovLicense: MIT
18748

Install this agent skill to your local

pnpm dlx add-skill https://github.com/artwist-polyakov/polyakov-claude-skills/tree/HEAD/plugins/sourcecraft-publisher/skills/sourcecraft-publisher

Skill Files

Browse the full folder contents for sourcecraft-publisher.

Download Skill

Loading file tree…

plugins/sourcecraft-publisher/skills/sourcecraft-publisher/SKILL.md

Skill Metadata

Name
sourcecraft-publisher
Description
Publish static page artifacts to SourceCraft Sites (Yandex infrastructure, works in Russia), with advisory image optimization and an original-image path. Use when a static page/React artifact needs to be deployed to SourceCraft under YYYY/YYYY-MM/page-slug directory layout.

SourceCraft Publisher

Publish already-built static artifacts to a SourceCraft Sites repository. Works from Russia (Yandex infrastructure).

This skill is the deployment/output layer for page artifacts created by other skills (e.g. telegram-channel-parser digest).

Required repository layout

Every published artifact must go into this path shape inside the target repo:

<year>/<year>-<month>/<page-slug>/

Example:

  • 2026/2026-03/ai-digest-week/

Never publish flat at repo root. Never skip the year or year-month nesting.

What this skill expects

Input should already exist as one of these:

  • a folder of built static files
  • a single HTML artifact plus local assets
  • a small static site ready to serve from a subdirectory

This skill does not do frontend design work. It packages and publishes what already exists.

Config

Read config/README.md for required environment variables and token setup.

cp config/.env.example config/.env

Required: SOURCECRAFT_TOKEN, SOURCECRAFT_REPO, SOURCECRAFT_SITE_URL.

Workflow

  1. Determine the publish date bucket:
    • year = YYYY
    • year-month = YYYY-MM
  2. Create or update target directory:
    • <year>/<year-month>/<page-slug>/
  3. Copy artifact files into that directory
  4. Verify there is an entrypoint (index.html normally)
  5. Ensure .sourcecraft/sites.yaml exists in repo root
  6. Commit and force-push to the SourceCraft repo
  7. Return the final public URL

Publishing command

python3 scripts/publish_static.py --source <dir-or-html> --slug <name> [--date YYYY-MM-DD] [--image-max-kb 500]

The script:

  • Clones the SourceCraft repo (shallow)
  • Ensures .sourcecraft/sites.yaml config exists
  • Copies artifact into YYYY/YYYY-MM/slug/
  • Optimizes oversized .jpg, .jpeg, .png, and .webp images before commit
  • Commits and force-pushes
  • Prints the final public URL

Image optimization

Image optimization is a recommendation, not a hard requirement. By default, the publishing script tries to keep each raster image under 500KB by stripping metadata, recompressing, and resizing long edges when needed.

Use --image-max-kb <kb> for a different target. Use --keep-large-images or --image-max-kb 0 when the user explicitly needs original-size images (for example, a full-resolution infographic, map, or downloadable media asset).

The original --source artifact is not changed. Optimization happens only after files are copied into the publish repo target directory. If Pillow/uv is unavailable or optimization fails, continue publishing originals and mention the warning.

Manual console run for a prepared artifact:

uv run --with pillow python3 scripts/optimize_images.py <artifact-dir> --max-kb 500

Slug rules

  • use lowercase letters, digits, and hyphens
  • keep it short and descriptive
  • avoid spaces, underscores, Cyrillic

URL contract

Always return the final public URL: <SOURCECRAFT_SITE_URL>/<year>/<year>-<month>/<page-slug>/

Pre-publish validation

Before pushing, verify:

  • artifact has index.html entrypoint
  • oversized raster images are optimized when practical, unless original-size sharing is intentional
  • no absolute local paths in HTML/CSS
  • no secrets in files
  • all local assets reachable from the target folder

Safety rules

  • do not delete unrelated directories in the repo
  • only replace contents of the target page directory
  • if overwriting, say so in the result
  • do not expose the token in output, logs, or committed files

References

Read if needed:

  • references/publish-checklist.md — operational checklist before pushing