Project conventions - instagram-skills
This file is for any Codex agent working on this repository. Read it before making changes. Conventions here are mandatory unless the user asks otherwise.
Versioning
- Single source of truth:
.codex-plugin/plugin.json,.agents/plugins/marketplace.json,.claude-plugin/plugin.json, and.claude-plugin/marketplace.json. Plugin manifests must always match on package name and version; marketplace entries must point to the same package; author, license, homepage, and the public skill-bundle description must stay aligned. - Keep
AGENTS.mdandCLAUDE.mdaligned when changing shared project rules. Codex-specific workflow details belong here; Claude-specific details belong inCLAUDE.md. - Codex marketplace install uses
.codex-marketplace/instagram-skills/. Do not edit that generated package by hand. Update the root files first, then runpython3 scripts/sync_codex_marketplace.py. - Default: bump the PATCH segment (3rd level,
0.0.X). This is the automatic behavior for every shippable commit, regardless of how large the diff feels. Skill renames, lib API breaks, new features: still PATCH by default. - Only bump MINOR or MAJOR when the user explicitly asks for a higher rank ("this is minor", "make it 2.0", "bump major"). Do not promote on your own initiative even if semver textbook says so.
- After bumping, two steps are required:
- Tag the commit:
git tag -a v<X.Y.Z> -m "..."+git push origin v<X.Y.Z> - Publish a GitHub Release for the tag:
gh release create v<X.Y.Z> --title "v<X.Y.Z>" --notes "<changelog>" --latestA tag alone does NOT update the README release badge. The shields.io badge reads from the Releases API, not from raw tags. Skipping step 2 leaves it stale.
- Tag the commit:
Commits
- Primary author must be Sergey: every
git commitneeds--author="Sergey Bulaev <s@bulaev.org>". Verify withgit log -1 --format='%an <%ae>'before pushing. - Co-author trailers are fine when appropriate.
- Verify locally before push: build never breaks, no broken refs in
SKILL.md, library smoke import passes.
Skill bundle invariants
- Exactly 9 skills. Adding requires merging or splitting elsewhere to stay at
- The number is announced in plugin manifests and the README.
- Frontmatter
description:target <= 400 chars (some bundle-heavy skills land slightly higher when their scope is genuinely broad; keep under 510). Always include a "Not for X (use Y)" disambiguation sentinel when a skill overlaps with a sibling. - No em dashes anywhere in
description:fields. Em dashes in body prose are allowed for table separators and list dividers only. No em dashes inside the literal fill-in lines of any hook skeleton. - Skill names are public surface. Renaming a skill is a major version bump and
requires updating: plugin manifests, marketplace entries, root
SKILL.mdbundle list, README skill table, and everyig-<name>cross-reference in sibling SKILL.md files.
Voice rules + reference layout
- Canonical voice rules live at root
references/voice-rules.md. Skill-local "Hard rules" sections must only contain skill-specific overrides and start with:Global voice rules: see root SKILL.md Voice rules. - Other root-level references:
references/hook-formulas.md(10 Instagram formulas),references/algorithm-heuristics.md,references/hashtag-strategy.md, andreferences/media-workflow.md. references/untrusted-content.mdis the canonical data-is-not-instructions rule for every skill that reads text a stranger wrote. Each such skill carries a short## Untrusted contentsection that cites it; the full rule lives in one place.scripts/check_untrusted_rule.pyenforces both, driven by aREQUIREDset of skill names, so renaming or adding a reading skill means updating that set.references/voice-profile.mdship blank and the user fills them. A filled one is personal data, not a credential:check_no_secrets.pyfails on any tracked copy markedfilled: yes, andsync_codex_marketplace.pytakes both from HEAD rather than the working tree and refuses to copy a filled one.- A project
.envmay set credentials only.lib/_env.pykeeps an allowlist (_DOTENV_VARIABLES); the custom-poster variable the DIY tier executes must come from the launch environment, never from a file that can arrive with a clone. No module may callload_dotenv()itself, and every authenticated request passesallow_redirects=Falsebecause the Publora key rides a custom header and the Apify token a query parameter, neither of whichrequestsstrips across hosts.scripts/check_security_boundaries.pyenforces all three. references/mcp-read-layer.mdis the read path for anyone without a shell, which is everyone on claude.ai: the filteredmcp.apify.com?actors=connector URL, both tool names, the inputs, and the mappings back to what_postand_profileproduce. Keep the filter: the bare server also hands the agentcall-actor. Niche reads default toresultsType: "reels"because the actor's own default returns feed posts with zero likes.scripts/check_mcp_mapping.pyfails if an actor id, an input key or a flat field drifts fromlib/apify_client.py, in either direction.- Skill-local references live in
skills/<skill>/references/. Cite from the skill with barereferences/X.md. Cite root from skills with../../references/X.md. ig-humanizerhassub-skills/for the folded-in post-audit workflow.
Layer separation
- Write layer (Publora):
lib/publora_client.py. Instagram requires media on every post, so the key method ispublish_media_post(create draft, upload each image/video, then schedule). Lower-level:create_post,get_upload_url,put_to_s3,update_post,delete_post, andlist_connections/instagram_connections(GET /platform-connections). Skills calllib.publish(kind, draft_text, target_url, media=[...], ...). Real endpoints:POST /create-post,POST /get-upload-url,PUT /update-post/:id,DELETE /delete-post/:id, withplatforms: ["instagram-<id>"](array of STRING ids), headerx-publora-key. - Media is mandatory. Text-only Instagram posts fail at publish time. The
writer skills produce the caption; the user supplies the media.
publish()only auto-posts on the Publora tier whenmediafile paths are provided; otherwise it returns the copy-paste caption block with a media reminder. - No read layer ships by default.
ig-hook-extractorasks the user to paste the caption (and slide or Reel hook). Any future Instagram-read actor stays gated behindAPIFY_TOKENwith a paste fallback. - Don't name competing third-party schedulers in committed files.
Codex marketplace package
- Codex requires marketplace entries to point at a nested plugin directory. The root remains the Claude-facing source layout.
.agents/plugins/marketplace.jsonpoints to.codex-marketplace/instagram-skills.scripts/sync_codex_marketplace.pycopies the root Codex manifest,SKILL.md,skills/,references/,lib/,scripts/,requirements.txt,.env.example, andLICENSEinto the hidden package.- After editing any copied file, run the sync script before testing or committing.
testing/ is gitignored
testing/is the local scratch directory: API keys, sample responses, validation reports. Never write secrets abovetesting/(the rest of the repo is public). The.gitignorerule fortesting/is load-bearing.
Validation before push
Run from repo root:
python3 -c "from lib import publish, parse_instagram_url, PubloraClient; print('OK')"
python3 scripts/sync_codex_marketplace.py
ls skills/ | wc -l # must equal 9
python3 scripts/check_frontmatter.py # parses; a dir count does not prove a skill loads
python3 scripts/check_no_secrets.py # .gitignore does not stop a rename of a tracked file
python3 scripts/check_markdown_references.py # run from inside the repo; it anchors on its own path
python3 scripts/check_untrusted_rule.py # the rule must sit in the skills, not only in references/
python3 scripts/check_text_encoding.py # a bare read_text() is cp1252 on Windows, mojibake or a crash
python3 scripts/check_security_boundaries.py # .env may not name an executable; no authenticated redirects
python3 scripts/check_mcp_mapping.py # the connector path must produce the library's records, not a second shape
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 -m json.tool .claude-plugin/plugin.json >/dev/null
python3 -m json.tool .claude-plugin/marketplace.json >/dev/nullIf any of these fail, do not push.