| name | inject-article |
| description | Ingest a single cutting-edge article, post, or talk — an X (Twitter) link, a blog post, a newsletter, a LinkedIn piece, or a YouTube video (transcript) — and weave it into the book as one well-placed, honestly-flagged citation. Use whenever the user hands you a link (especially an opinion piece, a practitioner thread, an industry-leader post, or a conference talk) and says "treat this as a source", "ingest this", "add this article", or "cite this". These sources are usually emerging opinion rather than verified research, so the citation must say so. The skill runs the whole chain for one link: fetch (web pages via download-source; X/Twitter via the fxtwitter JSON mirror; YouTube via the youtube-transcript-api tool) → save to sources/ → summarise into summaries/ → find the single best home in book/*.md → cite it (flagged as emerging opinion) → update references.json → run the book-style loop on just that section → verify and build. It is the lightweight, single-link cousin of research-topic, and it reuses download-source, summarise-source, enhance-book, and book-style. |
| compatibility | YouTube transcript fetching needs the youtube-transcript-api CLI (jdepoix/youtube-transcript-api), installed at ~/.local/bin/youtube_transcript_api. Everything else uses curl and the repo's own scripts. |
inject-article
The user hands you a link to a current, opinion-shaped article and wants it in the book — ingested,
summarised, and cited in exactly one apt place, with the citation making clear it is an emerging view
rather than established practice. This skill formalises that chain for a single link.
Unlike [[research-topic]], there is no search stage: the user has already chosen the source. The work is
to fetch it faithfully, place it well, and cite it honestly. The source may be a written piece (article,
post, thread) or a talk (a YouTube video, ingested as its transcript). Do one link at a time; if the user
pastes several, run the chain per link (the placement search must see the citations the previous link
added).
Why the "emerging opinion" flag matters
These sources are the frontier of practice: X threads, lab-leader essays, practitioner field guides. They
are valuable precisely because they are ahead of the literature — and unreliable for exactly the same
reason. Many are also self-interested (an engineer praising the tools they build; a CEO describing the
platform their company sells). The book's credibility rests on never dressing an opinion as a finding, so
every citation from this skill must name what the source is and hedge accordingly (see step 4).
The chain
1. Fetch the article faithfully
Get the real text, not a preview. X/Twitter and many sites block scrapers and WebFetch (you will see
402, 403, or a JS stub), so:
- X / Twitter links — hit the JSON mirror:
curl -sL https://api.fxtwitter.com/<user>/status/<id>.
A plain tweet's text is in .tweet.text; a long-form X article is in .tweet.article — its title is
.article.title, its body is the .article.content.blocks[] array (join each block's .text, mapping
header* types to headings and *-list-item to bullets). api.vxtwitter.com is a fallback.
- YouTube links — the source is the talk, not a page, so pull its transcript with the
youtube-transcript-api tool (jdepoix/youtube-transcript-api, installed; CLI at
~/.local/bin/youtube_transcript_api, so export PATH="$HOME/.local/bin:$PATH" first if it is not
found). It takes a bare 11-character video ID, not a URL — extract it from the link
(watch?v=, youtu.be/, /shorts/, /live/, /embed/), e.g.
echo "$URL" | sed -E 's#.*(v=|youtu\.be/|/shorts/|/live/|/embed/)([A-Za-z0-9_-]{11}).*#\2#'. Then:
youtube_transcript_api <VIDEO_ID> --format text --languages en (use --list-transcripts <ID> to see
what languages exist, and pick another if there is no English one). The transcript is the fetch;
its metadata is not — the CLI gives you no title, channel, or date. Get the title and channel from
the oEmbed endpoint (curl -s "https://www.youtube.com/oembed?url=<full-url>&format=json" →
title, author_name), and the publish date from the watch page or the description; if you cannot
confirm the date, say "n.d." rather than guess.
- Ordinary web pages/blogs — use [[download-source]] (its
html2md.py, or the curl + strip-tags
fallback). Verify you got the body, not a cookie wall.
- Capture, from the source itself: exact title, author (real name and/or handle), the author's role
(it decides the conflict-of-interest flag), publication date, and the canonical URL. Never guess a
surname; if the byline is a mononym or handle, cite it as given. For a video, the "author" is the
speaker or channel and the container is "YouTube".
Save the extracted text to sources/<topic>/<slug>.md with a metadata header (source URL, author + role,
date, and a one-line "Type:" noting it is an opinion/vision/practitioner piece, not peer-reviewed). Pick
the <topic> folder that matches the subject (e.g. ai-coding/, human-ai-future/, ai-governance/);
create it if new.
2. Summarise it
Run [[summarise-source]] (or write the summary directly, following that skill's format) into
summaries/<topic>/<slug>.md. Two requirements specific to this skill:
- The
> [!NOTE] block must flag the source's status prominently: opinion vs research, and any
conflict of interest (does the author sell or build what they are praising?).
- For a YouTube transcript, add one more caution. An auto-generated transcript has no punctuation you
can trust, no speaker labels, and it mis-hears names, numbers, and technical terms. So treat it as a
rough record: paraphrase the argument rather than quoting long stretches, and quote a phrase verbatim
only when it is plainly correct and you would stake the citation on it. Note in the header that the
text is an auto-caption transcript, so a later reader knows why the wording is loose.
- A long, multi-speaker source (a keynote block, a panel, a conference livestream) cannot be summarised
whole — do not try. Tens of thousands of words of speaker-unlabelled auto-caption will not let you
attribute specific claims to specific people without inventing. Instead, narrow to what is safely
citable: the framing you can verify (the event's own title/theme, the named opening speaker's thesis)
and one or two ideas the transcript states plainly. Say in the summary exactly what you are not
citing and why. The honest value of such a source is usually as a dated snapshot of the field's mood,
not as evidence — cite it that way.
- End with a short "Relation to the book" paragraph naming the one or two sections whose argument this
source most directly touches — this is your shortlist for step 3.
3. Find the single best home
Search the whole book for where the source's central claim reinforces (or usefully complicates) an
argument the book already makes. Prefer one strong placement over scattering the same source across
sections. Judgement calls:
- Place it where the source's thesis lands, not merely where a technique or phrase would fit.
- A cutting-edge opinion earns its place best next to cited research on the same point — as the
practitioner's echo of a finding, or an industry view set against the evidence — so the reader sees the
difference in weight.
- If the source genuinely supports two distinct, non-overlapping points, it may take two homes (as
[[enhance-book]] allows) — but the default is one. Record the runners-up in the summary rather than
citing everywhere.
- If it adds nothing the book does not already cover better, say so and cite nothing. A link is not an
obligation.
- If the source is the same argument by an author the book already cites — a talk of an article you
cited, a fuller version of the same post — do not add a second citation that says the same thing in
the same place. Refine the existing one instead: correct or complete the author's name if this source
verifies it (a conference listing or an oEmbed title often gives the full name a handle did not),
update the citation, and, if the reader would value it, add the new form as a companion reference on the
same in-text mention ("a case he makes both in a written guide [...] and a talk of the same name
[...]"). Only open a citation in a different section if this source makes a genuinely different
point there — and even then, weigh it against crowding a section that already carries the argument.
4. Cite it, flagged as emerging opinion
Weave one citation in via [[enhance-book]]'s conventions:
- APA-style inline link, first-mention-with-title, added to the chapter's References list (alphabetical)
and to
references.json (repo root). For a mononym/handle author, the intext is that name +
year (e.g. Thariq, 2026); the reference line uses it verbatim with "X (formerly Twitter)" as the
container.
- The prose must state the source's status in the sentence, in the author's voice — not a footnote.
Patterns that work: "a practitioner's account offered as emerging craft rather than tested practice";
"read it as an emerging industry view rather than a settled one — the author sells the tools they
describe". Then say why it is still worth citing (it names the same skill the research points to; it is
a striking statement of the book's own argument from an unexpected source).
- Keep to the house style: teach the idea plainly, keep a person in the sentence, no hype.
5. Run book-style on that section
Immediately run the [[book-style]] loop on only the section you edited (not the whole chapter). The
first draft of an inserted paragraph always carries a fingerprint or two — a mirror-payoff cap, a banned
abstraction like compounding, an em-dash chain. Do the rewrite → fresh-eyes check → fix loop until a
check pass on that section comes back clean. This step is mandatory: it is why the injected paragraph ends
up in the author's voice rather than the source's.
6. Verify and report
book-style/scripts/check_preservation.py against the pre-edit file: the only change is the added
citation URL; structure otherwise identical.- Citation reconciliation: the new in-text URL resolves to the chapter's References list and to
references.json; the reference list stays alphabetical.
cd quarto && ./build.sh → "Output created".- Report: source (title, author, role, date), where it landed and why, the exact hedge used, how many
book-style rounds the section needed, and any runner-up placements you noted but did not use.
Rules
- One link at a time; never batch the placement search.
- Verify metadata at the source — this flows into a citation. Never invent a surname or a date.
- Always flag status and conflict of interest in the citing sentence. This is the whole point of the
skill; a bare citation of an opinion piece is a bug.
- Do not commit or push unless the user asks (the book's standing rule).
- Prefer one honest citation to three eager ones; respect the option to cite nothing.
