docs: add README for every subdirectory

33 agent READMEs, 14 hand READMEs, 2 plugin READMEs
(echo-memory + hooks), and 2 skill READMEs
(custom-skill-prompt + custom-skill-python).

Each README documents the component's purpose, configuration,
and usage based on its TOML definition.

agents/academic-researcher/README.md

@@ -0,0 +1,23 @@
+# Academic Researcher
+
+Academic research agent. Searches scholarly papers, summarizes findings, and generates literature reviews.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs structured research methodology: scope, search, retrieve, evaluate, synthesize, and cite with proper academic standards.
+
+## Skills
+
+- `web_search`, `web_fetch`, `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run academic-researcher
+```

agents/analyst/README.md

@@ -0,0 +1,23 @@
+# Analyst
+
+Data analyst. Processes data, generates insights, creates reports.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a structured analysis framework: question, explore, analyze, visualize, and report with evidence-backed findings.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run analyst
+```

agents/architect/README.md

@@ -0,0 +1,23 @@
+# Architect
+
+System architect. Designs software architectures, evaluates trade-offs, creates technical specifications.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs principled system design: separation of concerns, performance-aware design, simplicity, and explicit trade-off evaluation.
+
+## Skills
+
+- `file_read`, `file_list`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run architect
+```

agents/assistant/README.md

@@ -0,0 +1,23 @@
+# Assistant
+
+General-purpose assistant agent. The default LibreFang agent for everyday tasks, questions, and conversations.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs versatile capabilities: conversation, task execution, research, writing, problem solving, agent delegation, and knowledge management.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`, `shell_exec`, `agent_send`, `agent_list`
+
+## Usage
+
+```bash
+librefang agent run assistant
+```

agents/code-reviewer/README.md

@@ -0,0 +1,23 @@
+# Code Reviewer
+
+Senior code reviewer. Reviews PRs, identifies issues, suggests improvements with production standards.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs prioritized review criteria: correctness, security, performance, maintainability, and style with severity-tagged feedback.
+
+## Skills
+
+- `file_read`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run code-reviewer
+```

agents/coder/README.md

@@ -0,0 +1,23 @@
+# Coder
+
+Expert software engineer. Reads, writes, and analyzes code.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a read-plan-implement-test-verify methodology with production quality standards and existing pattern adherence.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run coder
+```

agents/customer-support/README.md

@@ -0,0 +1,23 @@
+# Customer Support
+
+Customer support agent for ticket handling, issue resolution, and customer communication.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs empathetic ticket triage, systematic troubleshooting, knowledge base management, and escalation workflows.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run customer-support
+```

agents/data-scientist/README.md

@@ -0,0 +1,23 @@
+# Data Scientist
+
+Data scientist. Analyzes datasets, builds models, creates visualizations, performs statistical analysis.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a structured methodology: understand, explore, analyze, model, and communicate with a full statistical toolkit.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run data-scientist
+```

agents/debugger/README.md

@@ -0,0 +1,23 @@
+# Debugger
+
+Expert debugger. Traces bugs, analyzes stack traces, performs root cause analysis.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a reproduce-isolate-identify-fix-verify methodology with common bug pattern awareness and minimal-fix philosophy.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run debugger
+```

agents/devops-lead/README.md

@@ -0,0 +1,23 @@
+# DevOps Lead
+
+DevOps lead. Manages CI/CD, infrastructure, deployments, monitoring, and incident response.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs platform engineering expertise: CI/CD pipelines, container orchestration, IaC, observability, and security hardening.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run devops-lead
+```

agents/doc-writer/README.md

@@ -0,0 +1,23 @@
+# Doc Writer
+
+Technical writer. Creates documentation, README files, API docs, tutorials, and architecture guides.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs reader-first documentation with progressive disclosure, working code examples, and consistent style across READMEs, API docs, tutorials, and ADRs.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run doc-writer
+```

agents/email-assistant/README.md

@@ -0,0 +1,23 @@
+# Email Assistant
+
+Email triage, drafting, scheduling, and inbox management agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs email classification by urgency, professional drafting with tone adaptation, scheduling, template management, and thread summarization.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run email-assistant
+```

agents/health-tracker/README.md

@@ -0,0 +1,23 @@
+# Health Tracker
+
+Wellness tracking agent for health metrics, medication reminders, fitness goals, and lifestyle habits.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs health metrics logging, medication management, fitness goal tracking, habit building, and wellness reporting. Includes medical disclaimer.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run health-tracker
+```

agents/hello-world/README.md

@@ -0,0 +1,23 @@
+# Hello World
+
+A friendly greeting agent that can read files, search the web, and answer everyday questions.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs warm, concise, and helpful interactions as the first agent new users encounter.
+
+## Skills
+
+- `file_read`, `file_list`, `web_fetch`, `web_search`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run hello-world
+```

agents/home-automation/README.md

@@ -0,0 +1,23 @@
+# Home Automation
+
+Smart home control agent for IoT device management, automation rules, and home monitoring.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs device management, automation rule design, scene configuration, energy monitoring, security workflows, and IoT network troubleshooting.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run home-automation
+```

agents/legal-assistant/README.md

@@ -0,0 +1,23 @@
+# Legal Assistant
+
+Legal assistant agent for contract review, legal research, compliance checking, and document drafting.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs systematic contract review, legal research, compliance checking (GDPR, SOC 2, HIPAA, etc.), and plain-language explanations. Includes legal disclaimer.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run legal-assistant
+```

agents/meeting-assistant/README.md

@@ -0,0 +1,23 @@
+# Meeting Assistant
+
+Meeting notes, action items, agenda preparation, and follow-up tracking agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs structured agenda creation, transcript processing, action item extraction with owner/deadline tracking, and follow-up management.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run meeting-assistant
+```

agents/ops/README.md

@@ -0,0 +1,23 @@
+# Ops
+
+DevOps agent. Monitors systems, runs diagnostics, manages deployments.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs observe-diagnose-plan-execute-verify methodology with change management discipline and rollback planning.
+
+## Skills
+
+- `shell_exec`, `file_read`, `file_list`
+
+## Usage
+
+```bash
+librefang agent run ops
+```

agents/orchestrator/README.md

@@ -0,0 +1,23 @@
+# Orchestrator
+
+Meta-agent that decomposes complex tasks, delegates to specialist agents, and synthesizes results.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs task decomposition, specialist delegation via agent_send/agent_spawn, and result synthesis across the agent ecosystem.
+
+## Skills
+
+- `agent_send`, `agent_spawn`, `agent_list`, `agent_kill`, `memory_store`, `memory_recall`, `file_read`, `file_write`
+
+## Usage
+
+```bash
+librefang agent run orchestrator
+```

agents/personal-finance/README.md

@@ -0,0 +1,23 @@
+# Personal Finance
+
+Personal finance agent for budget tracking, expense analysis, savings goals, and financial planning.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs budget creation, expense categorization, savings goal tracking, debt payoff strategies, and financial health assessments. Not a licensed advisor.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`
+
+## Usage
+
+```bash
+librefang agent run personal-finance
+```

agents/planner/README.md

@@ -0,0 +1,23 @@
+# Planner
+
+Project planner. Creates project plans, breaks down epics, estimates effort, identifies risks and dependencies.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs scope-decompose-sequence-estimate-risk-milestone methodology with range-based estimates and risk-first planning.
+
+## Skills
+
+- `file_read`, `file_list`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run planner
+```

agents/recipe-assistant/README.md

@@ -0,0 +1,23 @@
+# Recipe Assistant
+
+Cooking assistant that helps with recipes, meal plans, ingredient substitutions, and portion adjustments.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs recipe discovery, portion scaling, ingredient substitution, meal planning, grocery list generation, and cooking technique guidance.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`, `web_search`
+
+## Usage
+
+```bash
+librefang agent run recipe-assistant
+```

agents/recruiter/README.md

@@ -0,0 +1,23 @@
+# Recruiter
+
+Recruiting agent for resume screening, candidate outreach, job description writing, and hiring pipeline management.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs merit-based resume screening, inclusive job descriptions, personalized outreach, structured interview prep, and pipeline tracking.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run recruiter
+```

agents/researcher/README.md

@@ -0,0 +1,23 @@
+# Researcher
+
+Research agent. Fetches web content and synthesizes information.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs decompose-search-deep dive-cross reference-synthesize methodology with source evaluation and confidence-rated findings.
+
+## Skills
+
+- `web_search`, `web_fetch`, `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run researcher
+```

agents/router/README.md

@@ -0,0 +1,23 @@
+# Router
+
+Native deterministic router. Dispatches tasks to specialist agents without using an LLM.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:router` |
+| Model | `default` |
+| Provider | `default` |
+
+This is a system-level agent. The `builtin:router` module performs deterministic routing and does not invoke an LLM.
+
+## Skills
+
+None configured.
+
+## Usage
+
+```bash
+librefang agent run router
+```

agents/sales-assistant/README.md

@@ -0,0 +1,23 @@
+# Sales Assistant
+
+Sales assistant agent for CRM updates, outreach drafting, pipeline management, and deal tracking.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs personalized outreach via AIDA framework, CRM data management, pipeline forecasting, call prep, and competitive intelligence.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run sales-assistant
+```

agents/security-auditor/README.md

@@ -0,0 +1,23 @@
+# Security Auditor
+
+Security specialist. Reviews code for vulnerabilities, checks configurations, performs threat modeling.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs OWASP Top 10 coverage, attack surface mapping, data flow tracing, and severity-rated findings with remediation guidance.
+
+## Skills
+
+- `file_read`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run security-auditor
+```

agents/social-media/README.md

@@ -0,0 +1,23 @@
+# Social Media
+
+Social media content creation, scheduling, and engagement strategy agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs platform-optimized content creation, content calendar planning, engagement strategy, analytics interpretation, and brand voice consistency.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run social-media
+```

agents/test-engineer/README.md

@@ -0,0 +1,23 @@
+# Test Engineer
+
+Quality assurance engineer. Designs test strategies, writes tests, validates correctness.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs behavior-driven testing philosophy with unit, integration, property, edge case, and regression test design using Arrange-Act-Assert pattern.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run test-engineer
+```

agents/translator/README.md

@@ -0,0 +1,23 @@
+# Translator
+
+Multi-language translation agent for document translation, localization, and cross-cultural communication.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs meaning-faithful translation, cultural adaptation, format preservation, software localization (i18n/l10n), and translation quality assurance.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run translator
+```

agents/travel-planner/README.md

@@ -0,0 +1,23 @@
+# Travel Planner
+
+Trip planning agent for itinerary creation, booking research, budget estimation, and travel logistics.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs day-by-day itinerary creation, destination research, budget planning at multiple tiers, accommodation recommendations, and multi-destination trip optimization.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_search`, `web_fetch`, `browser_navigate`, `browser_click`, `browser_type`, `browser_read_page`, `browser_screenshot`, `browser_close`
+
+## Usage
+
+```bash
+librefang agent run travel-planner
+```

agents/tutor/README.md

@@ -0,0 +1,23 @@
+# Tutor
+
+Teaching and explanation agent for learning, tutoring, and educational content creation.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs adaptive explanation using the Feynman Technique, Socratic teaching, problem-solving walkthroughs, learning plan design, and study skills coaching.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run tutor
+```

agents/writer/README.md

@@ -0,0 +1,23 @@
+# Writer
+
+Content writer. Creates documentation, articles, and technical writing.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs understand-research-draft-refine methodology with active voice, clarity-first style, and tone adaptation for docs, blog posts, and emails.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run writer
+```