garudust-hub

Open registry of tools and skills for Garudust Agent — install in one command, write in any language.

• Tools — executable scripts the agent can call (Bash, Python, Node.js, Rust)
• Skills — Markdown instruction sets that shape how the agent behaves in a workflow

Install a tool

# Short name — resolved via the hub index (default: garudust-org/garudust-hub)
garudust tool install weather

# Short name from a custom hub
garudust tool install weather --hub myorg/my-hub

Install a skill

garudust skill install git-workflow

Skills from this hub can be installed by short name. Other sources are also accepted:

# Short name — resolved via the hub index (default: garudust-org/garudust-hub)
garudust skill install git-workflow

# Short name from a custom hub
garudust skill install git-workflow --hub myorg/my-hub

# Full GitHub path
garudust skill install garudust-org/garudust-hub/skills/git-workflow

# Direct URL
garudust skill install https://example.com/skills/SKILL.md

# Well-known endpoint
garudust skill install well-known:https://example.com

Available tools

Tool	Description	Language	Requires
weather	Get current weather for a city (wttr.in)	Bash	—
hash_text	Compute SHA-256 hash of a string	Inline	—
read_qr	Decode a QR code from an image file	Bash	zbarimg
csv_to_json	Convert a CSV file to a JSON array of objects	Python	python3
file_info	Return size, MIME type, encoding, and line count of a file	Python	python3
token_count	Count characters, words, and estimated LLM tokens	Rust	rustc
fetch_title	Fetch the HTML title of a webpage	Python + uv	uv
extract_urls	Extract all URLs from an HTML or plain text file	Python + uv	uv
markdown_to_html	Convert a Markdown file to HTML	Rust + cargo	cargo
yaml_to_json	Convert a YAML file to formatted JSON	Node.js + npm	node, npm
facebook_post	Post text or photo to a Facebook Page via Graph API	Python + uv	uv, FACEBOOK_ACCESS_TOKEN
generate_image	Generate an image from a text prompt (HF FLUX.1-schnell, free tier)	Python + uv	uv, HF_TOKEN
view_image	Analyse an image with a vision LLM (Gemini Flash / OpenRouter fallback)	Python + uv	uv, provider config
email_send	Send email via Resend API or SMTP	Python + uv	uv, RESEND_API_KEY or SMTP vars
github_ops	GitHub operations — create PR, list issues, comment, merge, close	Python + uv	uv, GITHUB_TOKEN
line_oa	LINE Official Account — push/broadcast/reply messages and fetch user profiles	Python + uv	uv, LINE_CHANNEL_ACCESS_TOKEN
tts	Convert text to speech via Thai TTS provider	Python + uv	uv, provider config

Available skills

Skills load natural language instructions into the agent's context — they shape how the agent behaves, not what it can run.

garudust skill update                  # update all installed skills
garudust skill update facebook-workflow  # update a specific skill

Skill	Description	Install
log-analyst	Find error patterns, detect anomalies, trace requests, and summarise incidents from any log file	garudust skill install log-analyst
git-workflow	Conventional commits, branch naming, and PR best practices	garudust skill install git-workflow
code-review	Systematic PR review checklist — correctness, security, readability, and tests	garudust skill install code-review
facebook-workflow	Research a topic, write a post, generate a matching image with AI, and publish to a Facebook Page	garudust skill install facebook-workflow

Tools and skills that use a model

Some tools (e.g. view_image, generate_image) call an external LLM or image API. After installing, add a provider entry with your credentials and reference it in the tools section of ~/.garudust/config.yaml.

# ~/.garudust/config.yaml
providers:
  vision:
    name: google               # builtin provider — inherits base URL automatically
    key: ${GOOGLE_AI_API_KEY}  # ${ENV_VAR} or a literal key
    model: gemini-flash-latest
  vision-fallback:             # optional fallback
    name: openrouter
    key: ${OPENROUTER_API_KEY}
    model: nvidia/nemotron-nano-12b-v2-vl:free

tools:
  view_image:
    model: vision              # slot without "fallback" → primary (GARUDUST_MODEL / _API_KEY / _BASE_URL)
    model-fallback: vision-fallback  # slot with "fallback" → fallback (GARUDUST_FALLBACK_*)

Providers can be shared. If multiple tools use the same credentials, define the provider once and reference it from each tool.

Without garudust agent. Tools also read standard env vars directly (GOOGLE_AI_API_KEY, HF_TOKEN, etc.) so they work standalone or with other agent frameworks without any config.yaml changes.

---

Writing tools in different languages

Tools can be written in any language. The command field in tool.yaml is a plain shell command — set the interpreter there and declare runtime dependencies in requires.

Inline (no script file)

Best for one-liners using standard Unix tools. No script file needed.

command: printf '%s' {text} | shasum -a 256 | awk '{print $1}'

Limitations: Limited to what the shell and standard Unix utilities can express in one line.

---

Bash

tools/my_tool/
├── tool.yaml
└── run.sh

command: ./run.sh {param}

#!/usr/bin/env bash
set -euo pipefail
echo "$1"

Limitations: Available everywhere, but not ideal for complex data processing or structured output.

---

Python (stdlib only)

tools/my_tool/
├── tool.yaml
└── run.py

requires: [python3]
command: python3 ./run.py {param}

Limitations: Restricted to Python stdlib. Tools must not run pip install at runtime.

---

Python with external packages (via uv)

Use uv when the tool needs third-party packages. Declare each package with --with in the command — uv resolves, installs, and caches them automatically on first run. No pyproject.toml or requirements.txt needed.

tools/my_tool/
├── tool.yaml
└── run.py

requires: [uv]
command: uv run --with httpx --with beautifulsoup4 ./run.py {param}

Limitations: Requires uv (brew install uv). First run downloads packages; subsequent runs use the cache.

---

Node.js (built-in modules only)

tools/my_tool/
├── tool.yaml
└── index.js

requires: [node]
command: node ./index.js {param}

Limitations: Only Node.js built-in modules. No npm install at runtime.

---

Node.js with external packages (via npm)

Use a package.json when the tool needs npm packages. run.sh installs node_modules on first use and reuses them on subsequent runs.

tools/my_tool/
├── tool.yaml
├── run.sh
├── package.json
└── index.js

requires: [node, npm]
command: ./run.sh {param}

#!/usr/bin/env bash
set -euo pipefail
DIR="$(cd "$(dirname "$0")" && pwd)"
if [[ ! -d "$DIR/node_modules" ]]; then
    npm install --prefix "$DIR" --silent >&2
fi
node "$DIR/index.js" "$1"

Limitations: node_modules/ lives in the tool folder (gitignored). First run runs npm install.

---

Rust (stdlib only)

Single-file compilation with rustc. No external crates.

tools/my_tool/
├── tool.yaml
├── run.sh
└── main.rs

requires: [rustc]
command: ./run.sh {param}

#!/usr/bin/env bash
set -euo pipefail
DIR="$(cd "$(dirname "$0")" && pwd)"
BINARY="/tmp/garudust_my_tool"
if [[ ! -f "$BINARY" ]]; then
    rustc -O "$DIR/main.rs" -o "$BINARY"
fi
"$BINARY" "$1"

Limitations: Rust stdlib only. First run compiles (~1–3s); binary is cached at /tmp/.

---

Rust with external crates (via cargo)

Use a Cargo project when the tool needs external crates. run.sh runs cargo build --release on first use and caches the binary at /tmp/.

tools/my_tool/
├── tool.yaml
├── run.sh
├── Cargo.toml
├── Cargo.lock
└── src/
    └── main.rs

requires: [cargo]
command: ./run.sh {param}

#!/usr/bin/env bash
set -euo pipefail
DIR="$(cd "$(dirname "$0")" && pwd)"
BINARY="/tmp/garudust_my_tool"
if [[ ! -f "$BINARY" ]]; then
    cargo build --release --manifest-path "$DIR/Cargo.toml" >&2
    cp "$DIR/target/release/my_tool" "$BINARY"
fi
"$BINARY" "$1"

Limitations: First build downloads crates and compiles (~10–60s). target/ is gitignored. Do not commit pre-compiled binaries.

---

Quick comparison

	Inline	Bash	Python	Python + uv	Node.js	Node.js + npm	Rust	Rust + cargo
External packages	—	—	No	Yes	No	Yes	No	Yes
First-run overhead	—	—	—	pkg download	—	npm install	compile	compile + pkg
Requires	Nothing	Nothing	python3	uv	node	node, npm	rustc	cargo
Best for	One-liners	Shell glue	Data, text	Web, APIs	JS tooling	JS ecosystem	Performance	Performance + crates

---

Contributing a tool

See CONTRIBUTING.md for the full guide. Quick version:

1. Create a folder under tools/<tool_name>/
2. Add tool.yaml (validated against schemas/tool.schema.json)
3. Add your script file and make it executable (chmod +x)
4. Add an entry to index.yaml
5. Open a pull request — CI checks schema, index sync, and executable bits automatically

Contributing a skill

1. Create a folder under skills/<skill_name>/
2. Add SKILL.md with YAML frontmatter (name, description, version, permissions)
3. Optionally add shell scripts under skills/<skill_name>/scripts/ — they are auto-downloaded and made executable on install
4. Add an entry to index.yaml under skills:
5. Open a pull request

License

MIT