Jakeschincariol/instagram-agent-skill

What it is

This repository packages thirteen Claude skills for running an Instagram account, plus five dependency-free Python tools that run locally on plain text. The skills cover Reels, captions, carousels, stories, profile scoring, weekly planning, comments, replies, DMs, repurposing and post-audits. The README describes the design as write-first and publish-last: every skill ends with a copy-ready block and the account owner posts it manually.

The Python tools are the measurable part. hookscore.py ranks candidate hooks with a five-property panel against 26 scored hook formulas, beats.py turns a script into a timed beat sheet at a speaking rate, caption.py previews the 125-character feed window and lints length, hashtags and search terms, humanize.py and detect.py clean and score drafts for stock phrasing, invisible characters and structural tells, and swipe.py ranks captured reels by multiple over each account's own median.

It suits creators who already write their own posts and want a structured pre-publish check, and developers comfortable running short Python scripts and editing JSON configuration.

Getting started

There are three installation routes: ask Claude to install from the repository, clone and copy the skill folders into ~/.claude/skills/, or add the repository as a plugin marketplace and install instagram-agent. The project-local alternative is to copy the same folders into a repository's .claude/skills/. Without Claude Code, a single SKILL.md can be pasted at the top of a chat, but five Python tools are unavailable that way.

git clone https://github.com/Jakeschincariol/instagram-agent-skill.git
cp -r instagram-agent-skill/skills/ig-* ~/.claude/skills/

Before using the skills, fill in the voice profile: copy templates/voice.md to ~/.claude/instagram/voice.md, or give Claude three of your own reels and ask it to write the profile. Every skill reads that file.

Run the tools against local text files, for example:

python3 hookscore.py hooks.txt
python3 beats.py script.txt --target 30
python3 caption.py caption.txt --keywords "client contracts,freelance pricing"
python3 humanize.py draft.txt --report
python3 detect.py draft.txt
python3 swipe.py captured.tsv --out ~/.claude/instagram/swipe.md

Each prints a report; hookscore.py ranks hooks by score with a weakest-property line and dealbreaker notes, and caption.py prints the visible feed window plus PASS/WARN checks.

Constraints

The skills do not post, comment, follow or DM for you. The README explains that the Content Publishing API requires a Meta developer app, a linked Page, a long-lived token and app review, and that browser automation or third-party tools for posting violate Instagram's Terms of Use. /ig-viral is a human-paced reading workflow driven by your own browser over about ten accounts, not an automated crawler.

The detection panel is a set of local heuristics, not a call to GPTZero, Originality, Copyleaks or similar services, and it does not promise their verdicts. The invisible-character cleanup removes zero-width and format characters, not cryptographic watermarks. The hook scorer was measured on 74 YouTube Shorts hooks: it separated deliberately bad hooks at AUC 0.83, but a good creator's hits from misses at AUC 0.56, so it is useful for filtering weak hooks rather than predicting winners. A draft that needs a number you have not supplied is returned with a {{your number}} placeholder. Platform rules change; the README notes the hashtag cap moved to five per post in December 2025. The license is MIT.

HotRepo's take

The repository has one recorded weekly Python snapshot for 13 November 2026: 6,301 stars, 1,231 forks and 1,223 stars added that week, with a best position of 16 on that weekly Python list. The project created in September 2026, so that snapshot is the only ranking evidence available here and does not establish a longer trend. What stands out in the repository itself is the unusual amount of negative measurement: the README reports that the hook scorer does not separate hits from misses, that the formula classifier initially matched only 8% of real hooks before rewriting, and that the posting pipeline is deliberately absent. For a repository of this size, those admissions are the main technical signal.

Project source and documentation