---
name: co-fita-agent-skills
type: reference
title: "Custom Agent Skills — Telegram, Web Research, AutoResearch"
description: "The 3 custom skills: Telegram notification, web research pipeline (SearXNG + Crawl4AI), Deli AutoResearch"
tags: [skills, telegram, searxng, crawl4ai, auto-research, agent-tools]
timestamp: 2026-07-21
---

# Custom Agent Skills — Telegram, Web Research, AutoResearch

The Co-Fita Hyper-Harness includes three custom agent skills that extend the base agent capabilities. Each skill follows the Open-Closed principle — open for extension, closed for modification — and integrates with the harness's plugin registry architecture.

## Skill Overview

| Skill | Purpose | Integration Point |
|-------|---------|-------------------|
| telegram-notify skill | Send notifications to Alefita via Telegram | Governance, heartbeat, alerts |
| web-research-pipeline skill | Two-stage research: SearXNG discovery + Crawl4AI comprehension | Orchestrator Phase I (Ideation) |
| deli-autoresearch skill | Long-horizon autonomous task protocol | Orchestrator loop, state management |

## 1. Telegram Notify Skill

### Purpose

Send messages to Alefita's Telegram channel through the Co-Fita Hyper-Harness infrastructure. This skill implements the "outer loop" communication channel between the autonomous harness and the human leader (Líder Suprema).

### Architecture

```
Agent needs to notify
     │
     ▼
 scripts/telegram_notify.py
 Uses harness_core/plugins.py TelegramGateway
 Reads ~/.hermes/.env for credentials
     │
     ▼
 Telegram Bot API → Alefita's channel
```

### Prerequisites

The `~/.hermes/.env` file must contain:
```
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_HOME_CHANNEL=your_chat_id_here
```

### Usage

```bash
# Simple notification
uv run python scripts/telegram_notify.py --message "Research iteration 3 complete"

# Error alert
uv run python scripts/telegram_notify.py --message "Harness stalled for >2h" --level error

# Chancela request
uv run python scripts/telegram_notify.py \
  --message "Proposal #42: Add LoRA adapter for biomedicine domain" \
  --level chancela \
  --title "Nova Proposta"

# Heartbeat from Deli_AutoResearch
uv run python scripts/telegram_notify.py \
  --message "Iteration 7/∞ | Findings: 23 | Stale: 0" \
  --level heartbeat
```

### Message Levels

| Level | Emoji | Use Case |
|-------|-------|----------|
| `info` | ℹ️ | General notifications |
| `warning` | ⚠️ | Non-critical issues |
| `error` | 🚨 | Critical failures |
| `chancela` | 🏛️ | Approval requests |
| `heartbeat` | 💓 | Deli_AutoResearch heartbeat |

### Integration with Governance

The skill integrates with the governance system to:

1. Notify when a proposal reaches `AWAITING_CHANCELA` status
2. Notify when Congress is convened
3. Send QuinquennialPlan progress updates
4. Alert on harness failures captured by `event_bus.py`

### Integration with Deli_AutoResearch

| Layer | Function |
|-------|----------|
| **Heartbeat (L1)** | Periodic liveness notifications |
| **Stall Escalation (L2)** | When `stale_count >= 4`, flag for human attention |
| **Progress Reports** | After each successful iteration |
| **Structural Pivot** | Notify of new direction after forced pivot |

## 2. Web Research Pipeline Skill

### Purpose

A two-stage research skill combining SearXNG (meta-search discovery) with Crawl4AI (deep page reading). This skill supersedes basic `search_web` for depth-critical research.

### Architecture

```
Agent Question
     │
     ▼
 SearXNG (localhost:8888)
 GET /search?q=...&format=json
 → [{title, url, snippet}, ...]
 Role: DISCOVERY
     │ top-N URLs
     ▼
 Crawl4AI (localhost:11235)
 POST /crawl → {markdown: {raw_markdown, fit_markdown}}
 Role: COMPREHENSION (reads SPAs, renders JS)
     │ clean markdown
     ▼
 Agent ingests full content for reasoning
```

### SearXNG Component

**Endpoint**: `GET http://localhost:8888/search`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `q` | Yes | Search query |
| `format` | Yes | `json` |
| `categories` | No | `general`, `science`, `it`, `news` |

**Advantages over commercial APIs:**
- No API keys required
- Zero telemetry
- Unlimited queries
- 70+ search engines aggregated

**Usage:**
```bash
uv run python .agents/skills/web_research_pipeline/scripts/searxng_search.py "query"
uv run python .agents/skills/web_research_pipeline/scripts/searxng_search.py "query" --n 10
uv run python .agents/skills/web_research_pipeline/scripts/searxng_search.py "query" --categories science,it
```

### Crawl4AI Component

**Endpoint**: `POST http://localhost:11235/crawl`

| Feature | Capability |
|---------|------------|
| **JS Rendering** | Full Playwright headless browser |
| **Output Format** | `fit_markdown` (noise-filtered) or `raw_markdown` |
| **SPAs** | Handles JavaScript-rendered single-page applications |
| **MCP Integration** | Exposes `/mcp/sse` endpoint |

**Critical Technical Detail:**

The `markdown` field is NOT a plain string. It is a `MarkdownGenerationResult` dict:

```python
result["markdown"] = {
    "raw_markdown": "# Full page...",
    "fit_markdown": "# Filtered content...",    # Recommended for LLMs
    "markdown_with_citations": "...",
    "references_markdown": "...",
}
```

**Always prefer `fit_markdown`** — it removes boilerplate navigation, ads, and footers.

**Usage:**
```bash
# Read a single URL
uv run python .agents/skills/web_research_pipeline/scripts/crawl4ai_read.py "https://example.com"

# Read with max chars limit
uv run python .agents/skills/web_research_pipeline/scripts/crawl4ai_read.py "https://example.com" --max-chars 5000

# Full pipeline: search + read
uv run python .agents/skills/web_research_pipeline/scripts/research_pipeline.py "transformer architecture 2026"
```

### Extraction Strategies

| Strategy | Cost | Speed | Best For |
|----------|------|-------|----------|
| **Markdown** (default) | Free | Fast | General page reading |
| **JsonCssExtraction** | Free | Very fast | Sites with consistent HTML |
| **LLMExtraction** | Local GPU | Slow | Unstructured/complex content |
| **PruningFilter** | Free | Fast | Remove boilerplate noise |
| **BM25Filter** | Free | Fast | Topic-focused extraction |

### Integration with Orchestrator

The skill is registered as `WebCrawlerRegistry.register("crawl4ai")` in `harness_core/plugins.py`. The orchestrator's Phase I (Ideation) uses the pipeline:

1. SearXNG discovers relevant URLs
2. Crawl4AI reads full content of discovered URLs
3. OpenCode (via ACP) synthesizes and generates hypotheses

## 3. Deli AutoResearch Skill

### Purpose

A protocol framework for long-horizon autonomous tasks (days to weeks). It ships no executable code; instead it prescribes conventions for state persistence, stall detection, guardian layering, and behavioral constraints.

### The Three Failure Modes

| Failure Mode | Description | Common Cause |
|--------------|-------------|--------------|
| **Cognitive Loop** | Successive iterations try similar directions with diminishing returns | Context accumulation |
| **Stalling** | Agent finishes work, outputs summary, waits for feedback | Missing scaffolding |
| **Runtime Fragility** | Context compaction silently breaks the loop | Session dependencies |

### Behavioral Constraints

1. **Zero Interaction** — No prompting the user during a run; resolve ambiguity yourself
2. **Ready Means Execute** — The purpose of preparation is execution; no "should I submit?" questions
3. **Callback Means Report-Alive** — First action of every callback: update last_seen, check liveness
4. **Persist State to Files** — All progress written to `state/` files, not conversation memory
5. **Guardian/Worker Separation** — Heartbeat patrol only does liveness-check, restart, nudge

### State File Structure

```
{task}/state/
├── task_spec.md           # goal / milestones / success criteria
├── progress.json          # {iteration, total_findings, status, stale_count}
├── findings.jsonl         # accumulated findings (append-only)
├── directions_tried.json  # directions already tried
└── iteration_log.jsonl    # per-iteration summary

{task}/logs/
├── work.jsonl             # written by work agent; decisions tagged level=decision
├── orchestrator.jsonl     # written by orchestrator
└── heartbeat.jsonl        # written by heartbeat watchdog
```

### Stall Detection and Pivoting

| Mechanism | Rule |
|-----------|------|
| **Stall detection** | 0 new findings or metric drop → stale_count + 1 |
| **Forced pivot** | stale_count >= 2 → change structural constraint |
| **Human escalation** | stale_count >= 4 → flag for human attention |
| **Direction diversity** | New direction must differ from all tried |
| **Round cap** | 15 rounds or 30 minutes per session |

### Heartbeat Watchdog (Three Layers)

| Layer | Form | Depends on | Role |
|-------|------|------------|------|
| **L0** | Resident shell guard | No session | heartbeat stale > 2h → emergency patrol |
| **L1** | Durable cron, hourly | Living interactive session | check last_seen, restart timeouts |
| **L2** | Business loop | Each its own session | update own last_seen on callback |

### Validation Results

The framework has been validated on multiple task types:

| Paper | Pages | Citations | Self-rated |
|-------|-------|-----------|------------|
| Autonomous Research Agents | 59 | 228 | 8.0/10 |
| Continual Learning | 65 | 326 | 8.0/10 |
| Long-Horizon Decision-Making | 55 | 384 | 8.0/10 |
| Self-Play (285B RL experiment) | 75 | 217 | 8.6/10 |

**Longest continuous run**: 72 hours with 6 directional human inputs — zero operational intervention.

### Engineering Constraints

1. At most 5 large files per iteration; no single file over 300 lines
2. State injected via files, not conversation history
3. Validation must run between iterations
4. Citation-like content verified every 20 entries
5. Prefer diversity over digging one direction deeper
6. Unresolvable external failures escalate; never abandon silently

## Skill Integration Architecture

All three skills integrate via the Open-Closed principle:

```
┌─────────────────────────────────────────────────┐
│              PLUGIN REGISTRY                     │
│                                                  │
│  NotificationGateway ← telegram_notify           │
│  WebCrawlerRegistry  ← web_research_pipeline     │
│  LearningBackend     ← deli_autoresearch         │
│                                                  │
│  All register on import, no core modification    │
└─────────────────────────────────────────────────┘
```

### Gateway Pattern

Following the Hermes Agent analysis, the skills use an async message router pattern:

```
Telegram Gateway ←→ Harness Core ←→ SearXNG/Crawl4AI
     ↑                    ↑                ↑
     │                    │                │
  Human Loop        State Files      Research Loop
```

### Cron Integration

The Deli_AutoResearch skill specifies durable cron for heartbeat watchdog:

```python
# Hourly patrol (L1)
hourly patrol: 
  write timestamp
  check each loop's last_seen against interval×3
  restart if exceeded
  check each task's progress for stalls over 2h
  nudge if stalled
```

## Cross-References

- [[co-fita-deli-governance]] — Governance layer that triggers notifications
- [[co-fita-hyper-workspace]] — State files managed by AutoResearch
- [[co-fita-harness-wiki]] — Intellectual foundation and plugin architecture
- [[multi-agent-methodology]] — Multi-agent orchestration patterns