How zarazhangrui/follow-builders works
This repository is a packaged “skill” for an AI agent, centered around a centrally maintained content feed and a local digest-generation/delivery workflow.
High-level architecture
The repo has three main layers:
1. Skill / prompt layer
- Defines how an agent should behave when a user asks to set up or modify the “Follow Builders” digest.
- Lives mostly in SKILL.md and the prompts/ folder.
- This layer does not fetch content itself; it shapes summarization, translation, and digest tone.
2. Central feed production layer
- A GitHub Actions workflow updates the canonical feed on a schedule.
- Lives in .github/workflows/generate-feed.yml and the feed/source JSON files.
- This is the shared upstream data source for all users, which is why the skill does not require user API keys.
3. Local digest orchestration layer
- User-side scripts prepare the digest and optionally deliver it to a destination.
- Lives in scripts/ and is backed by local config/state.
- This is where user preferences, language choice, and delivery settings are applied.
Main subsystems
1) Source registry and content model
The repo distinguishes between curated source lists and generated feed artifacts:
• config/default-sources.json appears to define the canonical source set used by the skill.
• feed-blogs.json, feed-podcasts.json, and feed-x.json represent source-specific feed inputs or cached feed definitions for:
- official AI blogs,
- podcast channels,
- X/Twitter accounts.
This is the boundary between “what to follow” and “how to summarize it.”
2) Feed generation pipeline
The central feed is updated by a scheduled automation:
• .github/workflows/generate-feed.yml is the orchestration entrypoint.
• scripts/generate-feed.js is the main generator script.
• state-feed.json likely stores the last processed state, deduplication markers, or incremental generation metadata.
The README says the central feed is built from:
• blog articles via scraping,
• YouTube transcripts via Supadata,
• X/Twitter via the official API.
That means the feed-generation boundary depends on external content platforms, but those integrations are centralized so end users don’t manage credentials.
3) Digest preparation
Once the feed exists, the local skill turns it into a user-specific digest:
• scripts/prepare-digest.js likely selects new items from the feed, applies language preferences, and assembles a digest structure.
• prompts/digest-intro.md defines the top-level framing, tone, and layout of the digest.
• prompts/summarize-podcast.md, prompts/summarize-tweets.md, and prompts/summarize-blogs.md define content-type-specific summarization behavior.
• prompts/translate.md handles translation into Chinese or bilingual output.
This layer is where raw content becomes readable, concise summaries.
4) Delivery
Delivery is separated from preparation:
• scripts/deliver.js likely pushes the finished digest to an endpoint or messaging channel.
• The README mentions Telegram, email, Discord, WhatsApp, or in-chat delivery.
• Delivery credentials are local-only, stored in ~/.follow-builders/.env.
This is an important architectural boundary: content fetching is centralized, but delivery secrets remain on the user’s machine.
5) Configuration and validation
The repo includes configuration structure rather than hard-coded behavior:
• config/config-schema.json suggests user settings are validated against a schema.
• The README indicates the agent configures:
- frequency,
- time,
- language,
- delivery destination,
- summary style/verbosity.
This is the personalization layer, and it sits above the shared source registry and feed.
6) Examples and documentation
• examples/sample-digest.md shows the expected output shape.
• README.md and README.zh-CN.md explain the workflow and user-facing philosophy.
• SKILL.md is likely the agent-facing operational description.
These files are not runtime dependencies, but they define the contract the agent should follow.
Key data flows
A. Central content ingestion flow
1. Public content is pulled from curated sources.
2. The scheduled GitHub Action runs scripts/generate-feed.js.
3. Generated feed artifacts are written/updated, with state-feed.json helping maintain continuity.
4. The resulting feed becomes the shared upstream source for all users.
B. Local digest generation flow
1. The agent reads the central feed.
2. User preferences and delivery settings are applied.
3. Type-specific prompts summarize blogs, podcasts, and X posts.
4. Translation or bilingual formatting is applied if requested.
5. scripts/prepare-digest.js produces the final digest content.
C. Delivery flow
1. The prepared digest is handed to scripts/deliver.js.
2. A local delivery integration sends it to the configured target.
3. Secrets stay local; only public content is fetched centrally.
Architectural boundaries worth showing in a diagram
Central vs local
This is the most important boundary in the repo:
• Central, shared, automated: source fetching, feed generation, update cadence.
• Local, user-specific: preferences, prompt customization, delivery credentials, final dispatch.
Source retrieval vs summarization
Another clear boundary:
• Raw public content is ingested once into the feed.
• The digest is generated later, per user, with their preferred tone, length, and language.
Content types
The system treats three content families differently:
• podcasts,
• X/Twitter posts,
• official blogs.
Each has its own prompt and likely its own extraction/summarization path.
Technologies and operational characteristics
• Node.js is the scripting/runtime layer, based on scripts/package.json and scripts/package-lock.json.
• GitHub Actions is used for scheduled feed generation.
• Markdown prompt files are used as editable behavior specs for the agent.
• JSON is used for source lists, schema, and state.
What this repository is not
It is not a traditional web app or a single monolithic backend. It is closer to:
• a curated content pipeline,
• an agent skill package,
• and a delivery/orchestration toolkit.
The architectural center of gravity is the separation between:
• centrally maintained content aggregation,
• and local, preference-driven digest assembly and delivery.
If you draw the system, the most accurate diagram would show:
• public source platforms on one side,
• a GitHub Actions-backed feed generation service in the middle,
• and a local agent/runtime with prompt-driven summarization and delivery on the other side.
Main entry points: prepare-digest.js Prepare digest · SKILL.md SKILL.md · generate-feed.js Generate feed · default-sources.json Default sources
Components 20
Skill layer
Agent-facing guidance, prompts, and examples that shape digest behavior.
- SKILL.md · Primary agent-facing operating instructions for the Follow Builders skill.
SKILL.md - README · English overview of the workflow, architecture, and setup.
README.md - README zh · Chinese documentation for the same skill and workflow.
README.zh-CN.md - Sample digest · Reference digest showing the expected shape and tone of generated output.
examples/sample-digest.md - Digest intro · Top-level framing and tone for the final digest.
prompts/digest-intro.md - Blog summary · Summarization rules for blog content.
prompts/summarize-blogs.md - Podcast summary · Summarization rules for podcast content.
prompts/summarize-podcast.md - Tweet summary · Summarization rules for X/Twitter content.
prompts/summarize-tweets.md - Translate · Translation and bilingual output behavior.
prompts/translate.md
Central feed
Shared upstream feed generation and canonical source definitions.
- Default sources · Canonical curated source set used by the skill.
config/default-sources.json - Blog feed · Blog source feed artifact or cached input.
feed-blogs.json - Podcast feed · Podcast source feed artifact or cached input.
feed-podcasts.json - X feed · X/Twitter source feed artifact or cached input.
feed-x.json - Feed workflow · Scheduled automation that runs central feed generation.
.github/workflows/generate-feed.yml - Generate feed · Main generator that builds the shared feed from public sources.
scripts/generate-feed.js - Feed state · Incremental generation or deduplication state for the shared feed.
state-feed.json
Local orchestration
User-side digest preparation and delivery workflow.
- Config schema · Validation schema for user settings and delivery preferences.
config/config-schema.json - Prepare digest · Builds a user-specific digest from the shared feed and preferences.
scripts/prepare-digest.js - Deliver · Sends the prepared digest to the selected destination.
scripts/deliver.js - Scripts pkg · Runtime/package metadata for the Node-based orchestration scripts.
scripts/package.json
Connections 29
- SKILL.md → Digest intro: guides · Skill instructions are implemented through the digest framing prompt.
- SKILL.md → Blog summary: guides · Skill behavior includes blog-specific summarization rules.
- SKILL.md → Podcast summary: guides · Skill behavior includes podcast-specific summarization rules.
- SKILL.md → Tweet summary: guides · Skill behavior includes tweet-specific summarization rules.
- SKILL.md → Translate: guides · Skill behavior includes translation and bilingual formatting.
- README → SKILL.md: documents · README explains the agent skill and workflow.
- README zh → SKILL.md: documents · Chinese README documents the same skill.
- Sample digest → Digest intro: shows · Example output demonstrates the digest framing and structure.
- Default sources → Blog feed: drives · Canonical source registry feeds the blog source artifact.
- Default sources → Podcast feed: drives · Canonical source registry feeds the podcast source artifact.
- Default sources → X feed: drives · Canonical source registry feeds the X source artifact.
- Feed workflow → Generate feed: runs · GitHub Actions workflow executes the feed generator.
- Generate feed → Feed state: updates · Generator persists incremental state for continuity and deduping.
- Generate feed → Blog feed: builds · Generator produces the blog feed artifact.
- Generate feed → Podcast feed: builds · Generator produces the podcast feed artifact.
- Generate feed → X feed: builds · Generator produces the X feed artifact.
- Config schema → Prepare digest: validates · User configuration is validated before digest preparation.
- Scripts pkg → Generate feed: backs · Node runtime/package metadata backs the generator script.
- Scripts pkg → Prepare digest: backs · Node runtime/package metadata backs the digest preparer.
- Scripts pkg → Deliver: backs · Node runtime/package metadata backs the delivery script.
- Blog feed → Prepare digest: inputs · Prepared digest consumes blog items from the shared feed.
- Podcast feed → Prepare digest: inputs · Prepared digest consumes podcast items from the shared feed.
- X feed → Prepare digest: inputs · Prepared digest consumes X items from the shared feed.
- Digest intro → Prepare digest: frames · Digest preparation applies the top-level tone and layout.
- Blog summary → Prepare digest: summarizes · Blog prompt is used during digest assembly.
- Podcast summary → Prepare digest: summarizes · Podcast prompt is used during digest assembly.
- Tweet summary → Prepare digest: summarizes · Tweet prompt is used during digest assembly.
- Translate → Prepare digest: translates · Translation prompt is applied when language preferences require it.
- Prepare digest → Deliver: hands off · Prepared digest is passed to delivery.