Conventions

These conventions live in CLAUDE.md at the repo root and are enforced on every PR. Read them before touching code.

1. Environment variables → always through `.env`

Any new skill or tool that needs an API key / secret / URL MUST:

Read via process.env.<NAME> at factory time. Never hard-code.
Append an entry to .env.example (committed template).
For domain skills: set requires_env: ["<NAME>"] so the registry hides the skill when the var is missing.
For tool factories: return [] when the var is missing. Never throw at boot (reference: apps/agent/src/tools/providers/glassnode.ts).
Naming: UPPER_SNAKE, provider prefix first (COINGLASS_API_KEY, POLY_BUILDER_SECRET). Also update the env-vars inventory.

.env is git-ignored. Loading happens via process.loadEnvFile() in apps/agent/src/config/load-env.ts, imported as the FIRST line of every entrypoint. Shell-exported vars win over .env values.

2. Sandbox safety: never escape

All filesystem tools root at $dataDir/sandbox/files/ and resolve every path through resolveInSandbox() from apps/agent/src/tools/_shared/sandbox.ts. This blocks .. traversal and symlink escape. Tools are physically incapable of reading or writing apps/agent/src/ or user home. Do NOT invent a parallel file helper that bypasses this.

3. ESM import style

This repo is pure ESM ("type": "module" in package.json). All relative imports use .js extensions even in .ts source files:

import { foo } from "./bar.js";           // ✅ correct
import { foo } from "./bar";              // ❌ won't build

Import type explicitly: import type { DomainSkill } from "./types.js";.

4. License vigilance: only OSS / permissive content in the repo

Before vendoring any external SKILL.md / dataset / dependency, check the LICENSE. Past incident: Anthropic's official docx/pdf/pptx skills ship under a proprietary license forbidding "retain copies outside the Services." They cannot be committed to this repo. Use MIT/Apache-2.0 alternatives. When unsure, ask.

minara skills add surfaces license detection in its output. If it reports UNKNOWN or ⚠️ NONE, treat it as blocked until verified.

5. Document generation is TS-native, no Python

Word/PDF/PPT are generated via apps/agent/src/tools/document.ts using docx, pdf-lib, and pptxgenjs (all MIT). Do NOT add Python deps for document work. Do not re-introduce Anthropic's proprietary office skills.

6. Never commit without explicit user approval

Per project rules: never run git commit, git push, or gh pr create unless the user explicitly asks. Approval for one action is NOT approval for the whole flow. Never skip hooks (--no-verify), never force-push to main, never delete branches without confirmation.

What NOT to do

Don't add MCP plumbing for things that fit the in-house tool registry
Don't hard-code secrets or accept them as LLM-visible tool arguments
Don't write comments that just narrate what the code does
Don't add error handling for conditions that can't happen
Don't introduce a new abstraction for ≤ 3 similar call sites
Don't add Python to this Node repo
Don't commit files under .env / .minara/ / sandbox/ / dist/
Don't vendor non-OSS content into apps/agent/src/skills/external/

1. Environment variables → always through .env