moonlight-lupin/agent-skills instruction manual

1. Purpose, Claude Code classification, and installation

Agent Skills manual

`moonlight-lupin/agent-skills` is an MIT-licensed catalog of self-contained Agent Skills, primarily built and tested for Hermes Agent. Each skill lives in its own folder and normally uses a `SKILL.md` entry point, with optional scripts, references, examples, tests, or evaluation fixtures.

**Claude Code classification: context injection by adaptation; manual or skills-CLI installation.** The repository is not documented as a native Claude Code plugin suite. Its skills use Hermes tool names such as `web_search`, `web_extract`, `terminal`, `delegate_task`, and `cronjob`. Claude Code can receive a symlinked/copy-installed skill, but the user must map those tool names and adapt skill-loading conventions. The separate `skill-retrieval` component is explicitly Hermes-only and does not load in Claude Code. Accordingly, this repository relates to Claude Code as a portable skill collection, not as a reliable native plugin or hook integration.

To install the entire catalog with the documented multi-agent installer:

npx skills add moonlight-lupin/agent-skills

This installs skills under `.agents/skills/`, also uses `.claude/skills/`, and creates a hash-pinned `skills-lock.json`. The README states that `npx skills update` can refresh the installation. For one exact skill path:

gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md

For a user-scoped Claude Code installation:

gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md --agent claude-code --scope user

Manual setup is also documented:

git clone https://github.com/moonlight-lupin/agent-skills.git
cd agent-skills

Copy only wanted skill folders into the host’s skill directory, such as `~/.claude/skills/`. Never commit credentials or generated artifacts. Read each selected folder’s `SKILL.md` before use because dependencies and host-tool expectations differ.

2. Creative media skills

The **creative** domain contains three complementary workflows.

• **image-studio** creates images from prompts, edits or overlays existing images, and cleans up or enhances amateur photos. Its staged workflow brainstorms, prototypes cheaply, and then produces a final. The bundled `scripts/falgen.py` supports generation, editing, upscaling, background removal, and cost inspection. It requires Python 3.8+, `fal-client`, `requests`, and `FAL_KEY`; `FAL_ADMIN_KEY` optionally enables live balance display. This skill sends work to fal.ai, so perform its documented egress checks and review pricing before live calls.
• **clips-studio** creates short videos in three modes: text-to-video, animation of a still image, and camera movement. It follows a draft-first pipeline because rendering may take minutes and video is comparatively expensive. It writes local draft files only and does not publish or send them onward. It is not a replacement for a real shoot or measured 3D tour when literal accuracy matters. Requirements are Python 3.8+, `fal-client`, `requests`, and `FAL_KEY`, with optional `FAL_ADMIN_KEY`.
• **pexels-stock-photos** searches and downloads real stock photography through the Pexels API for presentations, articles, social posts, and similar uses. It uses `curl`, requires `PEXELS_API_KEY`, and has no Python runtime dependency. The documented limits are 200 requests per hour and 20,000 per month. Attribution must include the photographer and a Pexels link.

Safe, documented clips-studio previews and cost inspection are:

python scripts/falvid.py generate --prompt "abstract light sweep" --duration 5 --dry-run
python scripts/falvid.py animate --image still.png --prompt "slow light sweep across the product" --duration 5 --aspect 16:9 --dry-run
python scripts/falvid.py costs

Text-to-video rates in its registry are marked for verification, so confirm the first live generation on the fal dashboard. Use Pexels when a real photograph is required; use image-studio for generated or edited stills; use clips-studio when motion is the output.

3. Research, verification, monitoring, and source management

The first group of **research** skills organizes evidence and recurring investigation.

• **deep-research** runs iterative, source-grounded research. It structures evidence, ranks sources as primary, secondary, or tertiary, actively considers refuting evidence, starts reports with an overview, and labels statements `[VERIFIED]`, `[SOURCED]`, `[REASONED]`, or `[ESTIMATED]`.
• **entity-research** turns a person or company name into a cited dossier covering identity, ownership, adverse media, sanctions/PEP signals, and litigation. Its `screen_lists` helper performs token-based matches against partial OFAC, UK-OFSI, and UN public lists. A match is only an escalation signal; a miss is not clearance. Final review belongs to a qualified compliance/AML function. Public-person research requires a legitimate purpose. The helper is Python 3.8+ stdlib; live list checks need network access, while its documented self-test is offline.
• **fact-checker** verifies a targeted claim, assigns a confidence/status ranging from verified to outdated, and produces a cited report. Pair it with deep-research for wider context and source-tracker for retained citations.
• **media-analyzer** identifies rhetorical techniques such as loaded language, framing, and omission. It analyzes technique rather than assigning political labels.
• **source-tracker** maintains a persistent citation database, deduplicates URLs, adds topic tags, checks link health, and exports bibliographies.
• **news-monitoring** produces recurring, multilingual news digests, deduplicates items, and can use cron delivery through a capable host.
• **notebooklm-mode** answers questions from a source vault. It supports strict grounding or an augmented mode and pairs with library-rag for retrieval and deep-research for broader investigation.

These are agent workflows, not guarantees of factual or legal correctness. Claude Code users must substitute available search, fetch, scheduling, and delegation tools for the Hermes names in each skill. Prompt-only entries have no extra runtime dependency, but live research still depends on the host’s web capabilities and requires human checking of citations, dates, identity matches, and conclusions.

4. Enrichment, APIs, video research, model comparison, and scraping

The remaining research and extraction functions are more specialized.

• **people-enrichment** calls People Data Labs to enrich or search people and companies, returning profiles, work history, LinkedIn URLs, firmographics, and a styled `.xlsx`. It requires Python 3.8+, `openpyxl`, network access, and `PDL_API_KEY`. Live use sends names or companies to a third party and may return personal data; establish a legitimate and proportionate purpose and follow applicable privacy law. Offline checks include:

python scripts/enrich.py --self-test
python scripts/enrich.py person-enrich --input people.csv --dry-run
python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25 --dry-run
python scripts/enrich.py company-enrich --input companies.csv --output firms.xlsx

• **endpoint-probe** discovers and interprets exposed API or MCP surfaces, including REST, GraphQL, SOAP, and JSON-RPC. It supplies a probe script and interpretation guide.
• **youtube-topic-research** searches YouTube, obtains transcripts, and summarizes them. Documented dependencies are `ddgs`, `youtube-transcript-api`, `jinja2`, and `pyyaml`.
• **model-compare** performs blind multi-model A/B comparisons in simple, tool, coding, and review modes, plus an embedding benchmark. Its stdlib path needs no package; tool mode needs `SEARXNG_URL` or the `ddgs` CLI.
• **website-scraping** is a seven-step playbook: reconnoiter the site, choose the lightest extraction method that works, account for anti-bot defenses, and write clean JSONL plus a run manifest. It includes `scripts/recon.py`, extraction and browser references, examples, and eval fixtures.

A supplied browser example shows when agentic browsing is justified: dependent dropdowns that require ordered interaction and AJAX-aware polling. From that example’s `final_runs/run_1` location, its documented rerun is:

python final_runs/run_1/final_script.py

Use browser automation when navigation is the difficult part; once the rendered page is available, prefer ordinary extraction. Ensure scraping is authorized and review target-site requirements before collecting data.

5. Productivity and local document workflows

The **productivity** domain contains seven functions.

• **fill-template** performs local mail merge. It reads one `.docx` or `.xlsx` master and a `.csv` or `.xlsx` table, tokenizes the template, asks for confirmation, and generates one file per row. Its engine exposes `read_content`, `tokenise`, `tokens_in`, `load_rows`, and `generate`: respectively reading the master, inserting or handling tokens, discovering token names, loading tabular records, and producing outputs. Missing data is flagged `MISSING` rather than invented. Install `python-docx` and `openpyxl`; no network or credentials are needed.
• **travel-itinerary** converts business-trip material such as emails and PDFs into a structured itinerary, Markdown, `.ics` calendar output, and chat-friendly variants.
• **decision-log** maintains ADR-style decisions, links superseding decisions, and can schedule review reminders through cron.
• **document-converter** converts Markdown and HTML, CSV and JSON, YAML and TOML, plus PDF and Excel formats. Pandoc is required for PDF, `openpyxl` for Excel, and PyYAML is optional.
• **scheduled-summary** uses cron to create cross-session activity digests for messaging platforms, including activity that may not be visible in a chat channel.
• **file-organizer** scans a directory, proposes a structure, waits for confirmation, then moves files in chunks. Its core is stdlib-only; optional external LLM use through `urllib` supports DeepSeek, OpenRouter, or Ollama. Do not skip the proposal and confirmation stage.
• **task-brief** precedes substantial work with a short Goal, Context, Constraints, Assumptions, and Tooling brief. It asks at most two or three output-changing questions, waits for a short confirmation, executes against the agreed brief, and closes by checking the Goal. It skips trivial requests and uses no code, network, or credentials.

These workflows are designed to prevent invented data and premature action. Inspect generated documents, calendar details, conversions, file-move plans, and summaries before distributing them.

6. Agent operations and DevOps functions

The **agent-ops** skills maintain agents and skill libraries; **disk-cleanup** covers system maintenance.

• **claude-plugin-converter** is a two-phase converter: it first analyzes a Claude Code plugin and then generates a self-contained, installable Hermes plugin. This converts away from Claude Code; it does not install a Hermes plugin into Claude Code. It is beta and stdlib-only.
• **skill-maintainer** supports authoring, curation, upstream-drift tracking, synchronization, and publication of skill libraries. It is beta, uses stdlib plus `curl` for the GitHub API, and is Unix-first. Cron, curl, `which`, and shell loops are expected; Windows via WSL/MSYS2 is documented as untested.
• **log-analyzer** finds recurring error patterns, rate-limit clusters, timeout clusters, and tool failures in logs. It is stdlib-only and can feed scheduled-summary.
• **input-token-overheads** measures each source contributing to per-turn input tokens, ranks sources by cost, and directs attention to the largest consumers. PyYAML is optional. The skill is beta and uses evaluation fixtures rather than a listed pytest suite.
• **hermes-onboarding** provides a 21-step customer-onboarding process covering the gateway, dashboard, memory, search, guardrails, and maintenance cron jobs. It is a Hermes-oriented, prompt-only beta workflow.
• **disk-cleanup** surveys all mounted storage, separates proposed removals into safe and ask-first buckets, executes only an approved set, and verifies the space delta afterward. It is a prompt-only beta workflow.

Treat maintenance output as a proposal, not permission. Review generated plugin contents, upstream changes, logs that may contain secrets, token-measurement inputs, onboarding configuration, scheduled jobs, and every deletion candidate. For Claude Code, only the general workflows are portable; Hermes gateway, plugin, profile, cron, and dashboard operations need translation or are inapplicable. No supplied file documents direct Claude Code hooks for these functions.

7. Library RAG: conversion, indexing, search, and MCP

**library-rag** builds a personal semantic-search library: acquire content, convert it, embed it with NVIDIA NIM’s `nemotron-3-embed-1b`, store normalized vectors in sqlite-vec, and retrieve cited chunks. It supports English, Chinese, and other languages, incremental SHA-256 tracking, 15% overlap, and atomic per-file replacement so a failed re-index leaves the previous version searchable.

EPUB conversion splits chapters into frontmatter-bearing Markdown; PDF conversion uses `pdfplumber`, creates one `## Page N` section per page, and preserves tables for display while excluding duplicate table blocks from embeddings. `chunk_markdown()` splits `##`/`###` sections and carries parent breadcrumbs; `chunk_plain_text()` merges paragraphs with overlap. XML and JSON require a custom chunker registered in `discover_files()`.

From `research/library-rag`, documented conversion and indexing are:

python3 scripts/convert_epub_library.py \
    --epub /path/to/book.epub --slug my-book \
    --title "Book Title" --author "Author Name" --year 2024 \
    --md-root ~/.hermes/library/books/markdown
python3 scripts/rag_index.py

Build, rebuild, preview, and query with:

python3 scripts/rag_index.py
python3 scripts/rag_index.py --rebuild
python3 scripts/rag_index.py --dry-run
python3 scripts/rag_query.py "your search query"
python3 scripts/rag_query.py "search terms" --top-k 5
python3 scripts/rag_query.py "query" --source my-source-type --verbose

Requirements are Python 3.9+, packages in `requirements.txt`, an SQLite build permitting extension loading, and `NVIDIA_API_KEY`. Scripts first read the environment, then `HERMES_ENV` (default `~/.hermes/.env`). `OPENROUTER_API_KEY` activates the documented legacy bge-m3 path; old 1024-dimensional indexes must be rebuilt for the 2048-dimensional default. Optional MCP exposes `search(query, top_k, source_type)`, `stats()`, and `add_book(file_path, ...)`; `add_book` converts EPUB/PDF and indexes it in one call. The `mcp` package is needed only for that server. Users are responsible for having rights to indexed material.

8. Hermes skill retrieval, validation, testing, and operating limits

The repository’s only packaged plugin, **skill-retrieval**, is for Hermes Agent 0.20.0 or newer. It replaces a large full-description skill list with a compact names view, builds a stdlib BM25 inverted index, and injects only the top relevant descriptions per turn. Default top-K is 6. Discovery respects Hermes homes, named profiles, external and trusted project directories, disabled lists, and platform gates; caches are profile-specific. It normalizes paths for Windows and falls back to a standalone loader if Hermes core modules are unavailable. The reported token savings are measurements from one approximately 300-skill installation, not a universal guarantee.

From the repository root, install the plugin as documented:

ln -s "$(pwd)/plugins/skill-retrieval" ~/.hermes/plugins/skill-retrieval
pip install pyyaml

Restart Hermes so `register()` runs. To change result count before restart:

export SKILL_RETRIEVAL_TOP_K=8

To remove a symlinked installation:

rm ~/.hermes/plugins/skill-retrieval

For a copied installation, the documented command is `rm -rf ~/.hermes/plugins/skill-retrieval`; verify the path carefully first. Restart Hermes afterward. The prompt patch is in-process and disappears on restart. Do not attempt to load this plugin in Claude Code: the README explicitly says Claude Code lacks Hermes’s `pre_llm_call` and Python `register()` mechanisms and expects a different plugin manifest.

The catalog labels skills Stable or Beta. A check mark means a pytest suite; “evals” means routing/output fixtures checked without live-model execution. Repository-wide examples include:

python3 -m pytest plugins/skill-retrieval/tests/

Library-rag’s offline suite is:

pip install -r requirements.txt -r requirements-dev.txt
pytest -q

Tests do not establish live API quality, factual correctness, privacy compliance, or host compatibility. API keys, third-party processing, web access, cron execution, browser automation, personal data, filesystem moves, and deletions all require task-specific review.