AI Agent Skill · v0.2.1 · MIT

Drop-in skill mount for AI agents

The FinNotes Agent Skill lets Claude Code, Codex, OpenClaw, and any agent runtime that auto-loads project skills/ folders call the FinNotes commercial API without ever pasting fnp_ keys into chat. Credentials live in ~/.finnotes/credentials.env (mode 0600, off-limits to the model); the agent reads only the API response body via scripts/finnotes_request.py.

Install

Mount the skill into your runtime's skill folder

Pick the path that matches your agent runtime. All three give you the same files.

A. git clone (recommended)

# Claude Code (user-level)
git clone https://github.com/FinNotes-Intelligence/finnotes-news-and-data-skill ~/.claude/skills/finnotes-api

# Codex
git clone https://github.com/FinNotes-Intelligence/finnotes-news-and-data-skill ~/.codex/skills/finnotes-api

# OpenClaw
git clone https://github.com/FinNotes-Intelligence/finnotes-news-and-data-skill ~/.openclaw/skills/finnotes-api

# Project-local (any runtime that auto-loads ./.agent/skills/)
git clone https://github.com/FinNotes-Intelligence/finnotes-news-and-data-skill ./.agent/skills/finnotes-api

B. Direct ZIP download

Download v0.2.1.zip and extract into your runtime's skill folder (rename the extracted top-level dir to finnotes-api).

C. Inspect first

Browse the source at https://github.com/FinNotes-Intelligence/finnotes-news-and-data-skill — README has the full security model, script contracts, and contributing notes.

Quick start

Four steps from zero to a working agent

1. Mount the skill using one of the install paths above.
2. Mint a key at /api-keys. Click Create New Key, then in the one-time-secret modal click Download Agent JSON.
3. Hand the JSON to your agent. Just paste the downloaded file path. The skill instructs the agent to run python scripts/store_finnotes_key.py --handoff <path>, which writes ~/.finnotes/credentials.env (mode 0600) and ~/.finnotes/profile.json (non-secret metadata).
4. Ask your question. The agent (not you) calls python scripts/finnotes_request.py GET "/news?range=today&type=all" — the secret stays in credentials.env; only the API response reaches the model.

What's included

15 files, 140 KB, zero Python deps

• SKILL.md — the manifest agent runtimes read first.
• scripts/ — four Python tools (stdlib only) for credential storage, requests with structured error codes, profile inspection, and post-import handoff cleanup.
• references/ — point-in-time snapshots of the live /docs/for-ai/ docs (contract, guide, index) plus the skill-specific create-api-key-guide.md error-classification table and the finnotes-agent-key-handoff.sample.json shape reference.
• agents/openai.yaml — interface descriptor for OpenAI-format consumers.

For the freshest doc copy, fetch the live URL — the references/* files in this release are snapshots and may lag behind active changes.

Security model

Why the key never enters chat

• 0600 permissions: credentials.env is written via temp-file + atomic rename with mode 0600, and the skill's create-api-key-guide.md explicitly forbids reading it into model context.
• Handoff format validation: store_finnotes_key.py validates kind = "finnotes.agent_key_handoff", version = 1, credential.type = "bearer", and that the plaintext starts with fnp_ before writing anything.
• Two-step destructive ops: delete_finnotes_handoff.py refuses to run without --confirmed, which the agent passes only after explicit user confirmation.
• Error-code classification: finnotes_request.py maps HTTP status to agent-actionable signals (FINNOTES_KEY_REJECTED, FINNOTES_PERMISSION_REQUIRED, FINNOTES_POINTS_OR_BALANCE_PROBLEM, …) so the agent routes to the correct exception branch in create-api-key-guide.md instead of guessing.

Source · MIT · v0.2.1

FinNotes-Intelligence/finnotes-news-and-data-skill

File an issue with your runtime + exit code from finnotes_request.py. PRs welcome for additional runtime manifests, finer error classification, and Windows path fixes.