Skip to content

api_keys.md

Latest commit

 

History

History
236 lines (153 loc) · 9.98 KB

api_keys.md

File metadata and controls

236 lines (153 loc) · 9.98 KB
Raw

API Keys for Skills

Skills that call external APIs declare credential names in manifest.yaml under env_vars. Bundled skills resolve them with BaseSkill.credential(name) — host config first, then os.environ for local .env workflows. This page covers local setup, cloud injection, and skillware doctor checks.

Navigation

Skill keys vs agent keys

Kind Who consumes it Typical variables Where documented
Skill runtime keys skill.py when you call execute() Names in manifest.yaml env_vars Skill's catalog page + manifest
Agent / LLM keys Your chat client (Gemini, Claude, OpenAI, and similar) GOOGLE_API_KEY, ANTHROPIC_API_KEY, and similar Provider usage guides under docs/usage/

A single workflow may need both: for example, a skill that screens wallets may require ETHERSCAN_API_KEY, while your Gemini agent loop separately needs GOOGLE_API_KEY to run the model. Configure each name the code actually reads.

Framework environment variables

These are read by Skillware itself (loader and CLI), not by individual skills:

Variable Purpose
SKILLWARE_SKILL_PATH Extra filesystem roots for skill discovery (OS path separator between multiple entries). Without a config file, these are checked first (legacy order). When .skillware.yaml or global config.yaml exists, entries are merged into the external tier unless legacy.honor_skillware_skill_path: false. See CLI — path resolution.
SKILLWARE_CONFIG_DIR Override directory for global config.yaml (default: XDG ~/.config/skillware/ or %APPDATA%/skillware/ on Windows).
SKILLWARE_NO_VERSION_CHECK Set to 1 to disable the CLI version advisory (useful in CI and automation). See CLI reference.

Skill-specific names remain on each skill's catalog page and in manifest.yaml env_vars.

Local development

.env file (recommended)

Copy the repository root template and fill in values:

cp .env.example .env

Skillware can load .env into the process environment before skills run:

from skillware.core.env import load_env_file

load_env_file()  # reads `.env` in the current working directory by default

Run your script from the repository root (or pass an explicit path: load_env_file("/path/to/.env")).

Add .env to .gitignore (already ignored in this repository). Never commit real keys.

When developing Skillware from a branch, use pip install -e . so bundled skills load the in-tree BaseSkill.credential() helper.

Shell export

export ETHERSCAN_API_KEY="your_key"
python your_script.py

Exports apply only to the current shell session.

Cloud and CI

Inject the same variable names the skill expects; do not rename them unless you also provide a mapping layer (see below).

GitHub Actions (example):

env:
  ETHERSCAN_API_KEY: ${{ secrets.ETHERSCAN_API_KEY }}

Docker (example):

docker run --env-file .env your-image python examples/gemini_wallet_check.py

Containers / Kubernetes: mount secrets as environment variables with keys matching manifest.yaml (for example ETHERSCAN_API_KEY), not arbitrary secret aliases, unless your deployment template maps them.

Secret managers

Production hosts inject credentials without polluting global os.environ:

from skillware.core.loader import SkillLoader
from skillware.core.secrets import MappingSecretProvider, CallableSecretProvider

bundle = SkillLoader.load_skill("finance/wallet_screening")
config = SkillLoader.resolve_env_vars(
    bundle["manifest"],
    MappingSecretProvider({"ETHERSCAN_API_KEY": fetch_from_vault("etherscan")}),
)
skill = bundle["class"](config=config)

Or multi-skill:

from skillware import SkillContext

ctx = SkillContext(
    categories=["finance"],
    secret_provider={"ETHERSCAN_API_KEY": fetch_from_vault("etherscan")},
)
ctx.execute("finance/wallet_screening", {"address": "0x..."})
Provider Use when
MappingSecretProvider(dict) Secrets already fetched (Vault, K8s, Secrets Manager)
CallableSecretProvider(fetcher) Wrap STS / workload identity / KMS SDK in one callback
EnvSecretProvider() Resolve from existing os.environ (after load_env_file())
Custom get(key) class Full control (ephemeral tokens per call)

get(key) runs at resolution time — each SkillContext.execute() with a provider re-fetches, so short-lived tokens work. Use one context (or provider) per tenant.

Local dev unchanged: load_env_file() + default skill construction still reads .env via credential() fallback.

Check readiness: skillware doctor reports missing required env_vars (ENVS column).

Demo: examples/secret_provider_demo.py.

Variable names and custom deployments

Skills are written against specific environment variable names (for example ETHERSCAN_API_KEY). The manifest env_vars section documents meaning and whether each key is required.

If your organization uses different secret names:

  1. Preferred: Map at deploy time so the process still exposes the name the skill expects:

    export ETHERSCAN_API_KEY="$(vault read -field=key secret/etherscan)"

  2. Alternative: Use SkillLoader.resolve_env_vars() and pass config= when constructing the skill (see Secret managers). Skills that honor self.config receive injected values without global env mutation.

  3. Avoid: Renaming the variable in .env to MY_ETHERSCAN_KEY without exporting ETHERSCAN_API_KEY—the skill will behave as if the key is missing.

When contributing a new skill, declare every external credential under env_vars in manifest.yaml and list the same names on the skill's documentation page with a link to this guide.

Security practices

  • Never hardcode API keys in skill.py, notebooks, or documentation.
  • Never commit .env, key files, or CI logs containing secrets.
  • Use least-privilege keys (read-only or scoped APIs where providers allow it).
  • Rotate keys if they are exposed; revoke compromised keys at the provider.
  • Prefer secret managers or platform secret stores for production, not plaintext files on servers.
  • Do not print environment variable values in skill output or logs.

Report security concerns per SECURITY.md.

Illustrative examples

These patterns apply to many skills; see individual skill pages for exact variable names and requirements.

Dedicated agent mailbox (Gmail) — same rule as a dedicated agent wallet

office/gmail_handler signs into Gmail as GMAIL_ADDRESS using GMAIL_APP_PASSWORD. Treat this like AGENT_WALLET_PRIVATE_KEY for defi/evm_tx_handler:

Do Do not
Create a new Gmail account used only by the agent Reuse your personal, work, or primary inbox
Generate an App Password after 2FA (Google App Passwords) Paste the App Password into chat, tool args, or git
Enable IMAP in Gmail settings for that account Store credentials in skill.py or committed YAML
Revoke the App Password when retiring the agent Grant org-wide or shared-mailbox access without explicit operator consent 
export GMAIL_ADDRESS="agent-mailbox@example.com"
export GMAIL_APP_PASSWORD="your-16-char-app-password"

Optional path overrides: GMAIL_ADDRESSBOOK_PATH, GMAIL_SIGNATURE_PATH, GMAIL_SIGNATURE_HTML_PATH, GMAIL_SIGNATURE_PLAIN, GMAIL_SIGNATURE_PROFILE, GMAIL_SCAN_STATE_PATH, GMAIL_SEND_LEDGER_PATH. Operator setup (address book, signatures, multi-profile signatures, persistence): skillware mail and Gmail Handler.

Preview and confirmation gates apply before send/reply; read the skill instructions.md before enabling live mail on any host agent.

External data API (required key)

A skill that fetches on-chain data may require a provider key before execute() returns useful results. Set the name from its manifest (illustrative):

export ETHERSCAN_API_KEY="your_etherscan_key"

If the key is missing, the skill should return a structured error rather than crash the host agent.

Optional provider key

Some skills support a free tier when a key is absent and upgraded limits when present. The skill page and env_vars.required field state whether the key is optional.

Optional LLM path inside a skill

Some skills optionally call a cloud model for one step (for example policy clause review). That path may require GOOGLE_API_KEY only when enabled via parameters such as use_llm_evaluator: true. The skill page lists when the key is needed.

Local-only skills

Skills that talk only to localhost (for example a local Ollama instance) may not use API keys at all. No configuration is required beyond running the local service.

Related documents