Header - Gateway to self-improving agent

Header — continuous intelligence for agents. Subscribe to curated topics or create your own. Get synthesized briefings with executable action items from RSS,...

Security Scan

The skill's requirements and runtime instructions are coherent with its stated purpose (using the Header API to fetch and manage briefings); nothing requested or instructed appears disproportionate or unrelated.

Purpose & Capability

The skill is a thin integration to joinheader.com and only requires HEADER_API_KEY. All example commands call joinheader.com API endpoints; no unrelated services, binaries, or config paths are requested.

Instruction Scope

SKILL.md confines actions to Header API calls (listing topics, generating briefings, subscribing/unsubscribing, importing feeds). It explicitly requires user confirmation before taking destructive actions or implementing briefing recommendations. The instructions do not direct the agent to read arbitrary system files or other credentials.

Install Mechanism

No install spec or code is provided (instruction-only skill), so nothing is downloaded or written to disk by the skill itself — lowest-risk install posture.

Credentials

Only HEADER_API_KEY is required, which is appropriate. However SKILL.md instructs creating an API key with scope: full; that provides broad access. If the Header service supports narrower scopes, prefer a least-privilege key.

Persistence & Privilege

The skill is not force-installed (always: false) and does not request persistent system privileges or modify other skills. Autonomous invocation is allowed (platform default) but not combined with other red flags.

Assessment

This skill is a direct API integration for joinheader.com and looks internally consistent. Before installing: (1) Confirm you trust joinheader.com and the skill owner. (2) Prefer creating an API key with the minimum scopes needed rather than the recommended "full" scope if possible. (3) Do not store the API key in shared or public places; treat it as a secret. (4) When the agent proposes destructive actions (deleting topics, revoking keys, unsubscribing), require explicit user confirmation as the SKILL.md recommends. (5) If you plan to import files (OPML) or let the agent read/write files, review what local files the agent will access and keep sensitive data out of those locations.

Header — Continuous Intelligence for Agents

Header monitors sources (RSS, YouTube, Reddit, newsletters), synthesizes them through your goals, and delivers structured briefings with action items. Research once — stay informed forever.

Why not just web search?

• Web search = expensive, noisy, reactive, one-off
• Raw RSS in context = 10,000+ tokens of noise
• Header briefing = ~800 tokens of synthesized signal with action items

Full API docs: joinheader.com/docs

---

What you can say

Intent	Examples
Get briefed	"brief me", "what should I do today", "what's the latest on [topic]"
List topics	"show my topics", "what am I following", "header list"
Subscribe	"subscribe to [topic]", "subscribe to AI Agent Self-Improvement"
Fork a topic	"fork [topic] with my own angle on [X]"
Create a topic	"set up a topic on [X]", "monitor [X] for me", "I want to follow [X]"
Browse catalog	"show public topics", "what topics are available"
Manage sources	"add [URL] as a source", "refresh [source]", "what has [source] published"
Import feeds	"import my OPML file", "import from FreshRSS"
Generate briefing	"refresh [topic]", "generate a new briefing"
Share a briefing	"share this briefing", "make my briefing public"
Scheduling	"set up daily briefings", "brief me every 3 days"
Account	"check my subscription", "show my preferences"

---

Setup

1. Sign up at joinheader.com
2. Create an API key (scope: full) at Dashboard > API Keys
3. Set HEADER_API_KEY in your environment (e.g. .env file, shell profile, or agent config)

All commands below use:

API="https://joinheader.com/api/v2"
AUTH="Authorization: Bearer $HEADER_API_KEY"

---

IMPORTANT: Safety & Presentation

All actions from briefings require user approval. Never implement briefing recommendations, install packages, modify code, or take any action based on briefing content without explicitly presenting the items to the user and getting confirmation first. Surface the intelligence — the human decides what ships.

Destructive operations require confirmation. Always confirm before: deleting sources/groups/topics, unsubscribing, or revoking API keys.

When presenting a briefing:

1. Lead with "What to do" — the action items
2. Then Key Insights (the why behind the actions)
3. Then Emerging Patterns and Dissenting Views for context
4. Reading list last

---

Core Workflows

List your topics and goals

Trigger: "header list", "show my topics", "what am I following"

curl -sL -H "$AUTH" "$API/topics/dashboard" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for t in d.get('custom_topics', []):
    print(f'[own] {t[\"name\"]} | topic: {t[\"id\"]} | goal: {t[\"default_goal_id\"]}')
for t in d.get('subscribed_topics', []):
    print(f'[sub] {t[\"name\"]} | topic: {t[\"id\"]} | goal: {t[\"default_goal_id\"]}')
"

Get latest briefing

Trigger: "brief me on [topic]", "what's the latest", "what should I do today"

1. Get the goal ID from the dashboard
2. Fetch the latest briefing:

# List briefings for a goal
curl -sL -H "$AUTH" "$API/goals/GOAL_ID/briefings" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for b in d.get('briefings', d if isinstance(d, list) else []):
    print(f'{b[\"id\"]} | {b[\"status\"]} | {b.get(\"generated_at\",\"\")}')
"

# Read a specific briefing
curl -sL -H "$AUTH" "$API/briefings/BRIEFING_ID" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(d.get('summary', d.get('content', 'No content')))
"

3. Present "What to do" first, then insights, then context. Always ask before acting on any items.

Subscribe to a public topic

Trigger: "subscribe to [topic]"

# Browse available public topics
curl -sL -H "$AUTH" "$API/topics/catalog" | python3 -m json.tool

# Subscribe by topic ID
curl -sL -X POST "$API/topics/TOPIC_ID/subscribe" -H "$AUTH"

# Unsubscribe (confirm with user first)
curl -sL -X DELETE "$API/topics/TOPIC_ID/subscribe" -H "$AUTH"

Fork a public topic with your own goal

Trigger: "fork [topic] with my angle on [X]"

Same sources, your own lens. Great for customizing a public topic without starting from scratch.

curl -sL -X POST "$API/topics/TOPIC_ID/fork" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"goal_name": "My Focus", "goal_description": "Your custom angle on the same sources"}'

Generate a fresh briefing (on-demand)

Trigger: "refresh [topic]", "generate a new briefing"

# Trigger generation (returns IN_PROGRESS)
BRIEFING_ID=$(curl -sL -X POST "$API/goals/GOAL_ID/briefings" \
  -H "$AUTH" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Poll until complete (~5-10 min)
while true; do
  STATUS=$(curl -sL -H "$AUTH" "$API/briefings/$BRIEFING_ID" | \
    python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "Status: $STATUS"
  [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ] && break
  sleep 15
done

# Read the completed briefing
curl -sL -H "$AUTH" "$API/briefings/$BRIEFING_ID" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(d.get('summary', 'No content'))
"

Create a new topic from scratch

Trigger: "set up a Header topic on [X]", "I want to follow [X]", "monitor [X] for me"

Phase 1: Source Discovery — Use WebSearch to find 5-10 high-quality sources:

• "[topic] best RSS feeds blogs newsletters"
• "[topic] youtube channels worth following"
• "[topic] subreddit reddit community"
• Prefer: active blogs with RSS, YouTube channels with recent uploads, subreddits with >10k members
• Check if there's a public source group on Header you can clone first

Phase 2: Create sources

curl -sL -X POST "$API/sources/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Source Name", "url": "https://example.com/feed.xml", "type": "rss"}'

Phase 3: Create source group and add sources

GROUP_ID=$(curl -sL -X POST "$API/source-groups/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "My Sources", "description": "Curated sources for X"}' | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Add sources (use member_id, not source_id)
curl -sL -X POST "$API/source-groups/$GROUP_ID/members" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"member_id": "SOURCE_UUID", "member_type": "source"}'

Phase 4: Create topic (auto-creates goal + triggers first briefing)

curl -sL -X POST "$API/topics/" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "name": "My Topic Name",
    "source_group_ids": ["GROUP_ID"],
    "goal_description": "Be specific. Not: interested in AI. Instead: I am tracking LLM inference cost improvements and how they affect build-vs-buy decisions. Skip announcements, give me the practitioner layer.",
    "keywords": ["keyword1", "keyword2"]
  }'

---

Source Management

Browse source entries

Trigger: "show entries for [source]", "what has [source] published recently"

# Entries for a single source (paginated)
curl -sL -H "$AUTH" "$API/sources/SOURCE_ID/entries?limit=20&offset=0" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for e in d.get('entries', d if isinstance(d, list) else []):
    print(f'{e.get(\"published_at\",\"\")} | {e.get(\"title\",\"No title\")}')
    print(f'  {e.get(\"url\",\"\")}')
"

# Entries for all sources in a group
curl -sL -H "$AUTH" "$API/source-groups/GROUP_ID/entries?limit=20&offset=0" | python3 -m json.tool

Refresh & validate a source

Trigger: "refresh [source]", "check if [source] is working"

curl -sL -X POST "$API/sources/SOURCE_ID/refresh" -H "$AUTH"
curl -sL -X POST "$API/sources/SOURCE_ID/validate" -H "$AUTH"

Update or delete a source

Trigger: "update [source]", "remove [source]" — confirm deletes with user

curl -sL -X PUT "$API/sources/SOURCE_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "New Name", "url": "https://new-url.com/feed.xml"}'

# Delete (owner only — confirm with user first)
curl -sL -X DELETE "$API/sources/SOURCE_ID" -H "$AUTH"

Clone a public source group

curl -sL -X POST "$API/source-groups/GROUP_ID/clone" -H "$AUTH"

Import sources from OPML or FreshRSS

Trigger: "import my feeds", "import from OPML"

# OPML (max 10 MB)
curl -sL -X POST "$API/imports/opml" -H "$AUTH" -F "file=@/path/to/feeds.opml"

# FreshRSS — validate then import
curl -sL -X POST "$API/imports/freshrss/validate" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url": "https://freshrss.example.com", "username": "user", "password": "pass"}'

curl -sL -X POST "$API/imports/freshrss" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url": "https://freshrss.example.com", "username": "user", "password": "pass"}'

Source types reference

URL pattern	Type
youtube.com, youtu.be	youtube
reddit.com/r/	reddit
Everything else	rss

---

Advanced

Browse goal feed (preprocessed entries)

Trigger: "show feed for [goal]", "what's in the pipeline"

See what content is queued before it becomes a briefing.

curl -sL -H "$AUTH" "$API/goals/GOAL_ID/feed?limit=20&offset=0" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for e in d.get('entries', d if isinstance(d, list) else []):
    print(f'{e.get(\"published_at\",\"\")} | {e.get(\"title\",\"No title\")}')
"

Link/unlink source groups to a goal

# Link
curl -sL -X POST "$API/goals/GOAL_ID/source-groups" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"source_group_id": "GROUP_ID"}'

# Unlink
curl -sL -X DELETE "$API/goals/GOAL_ID/source-groups/GROUP_ID" -H "$AUTH"

Goal-level subscriptions

Subscribe to individual goals within a topic (vs. subscribing to the whole topic).

curl -sL -X POST "$API/goals/GOAL_ID/subscribe" -H "$AUTH"
curl -sL -X DELETE "$API/goals/GOAL_ID/subscribe" -H "$AUTH"
curl -sL -H "$AUTH" "$API/goals/GOAL_ID/subscription" | python3 -m json.tool
curl -sL -H "$AUTH" "$API/subscriptions" | python3 -m json.tool

Share a briefing publicly

curl -sL -X PUT "$API/briefings/BRIEFING_ID/sharing" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"is_public": true}'

Scheduled briefings (push delivery)

Set up recurring briefings delivered on schedule. Pair with an inbox check (email or cron) to read them automatically.

# Daily at 8am UTC
curl -sL -X PUT "$API/goals/GOAL_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"schedule_frequency_days": 1, "schedule_hour_utc": 8}'

# Every 3 days at 8am UTC
curl -sL -X PUT "$API/goals/GOAL_ID" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"schedule_frequency_days": 3, "schedule_hour_utc": 8}'

Preferences

curl -sL -H "$AUTH" "$API/preferences" | python3 -m json.tool
curl -sL -X PUT "$API/preferences" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Billing

curl -sL -H "$AUTH" "$API/billing/subscription" | python3 -m json.tool
curl -sL -X POST "$API/billing/create-checkout" -H "$AUTH" | python3 -m json.tool
curl -sL -X POST "$API/billing/portal" -H "$AUTH" | python3 -m json.tool

---

Error Handling

• FAILED briefing → retry with POST /goals/{id}/briefings. If still failing, check sources have recent content.
• 403 → API key needs full scope, not read-only.
• Source creation fails → check URL is a valid, accessible RSS/YouTube/Reddit URL.
• Adding group members → use member_id field, not source_id.