| 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
- Determine the publish date bucket:
- year =
YYYY
- year-month =
YYYY-MM
- Create or update target directory:
<year>/<year-month>/<page-slug>/
- Copy artifact files into that directory
- Verify there is an entrypoint (
index.html normally)
- Ensure
.sourcecraft/sites.yaml exists in repo root
- Commit and force-push to the SourceCraft repo
- 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
