diff --git a/CLAUDE.md b/CLAUDE.md
index 142de26b..e08524ea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -192,7 +192,9 @@ pnpm multica credentials init
 
 Creates:
 - `~/.super-multica/credentials.json5` (LLM providers + built-in tools)
-- `~/.super-multica/skills.env.json5` (skills / plugins / integrations)
+
+Skill-specific API keys go in `.env` files within each skill's directory:
+- `~/.super-multica/skills/<skill-id>/.env`
 
 ## Atomic Commits
 
diff --git a/docs/credentials.md b/docs/credentials.md
index 558d499f..36c3e9e2 100644
--- a/docs/credentials.md
+++ b/docs/credentials.md
@@ -8,7 +8,6 @@ multica credentials init
 
 Creates:
 - `~/.super-multica/credentials.json5` — LLM providers + tools
-- `~/.super-multica/skills.env.json5` — skill/plugin API keys
 
 Example `credentials.json5`:
 
@@ -27,6 +26,32 @@ Example `credentials.json5`:
 }
 ```
 
+## Skill API Keys
+
+Skill-specific API keys are stored in `.env` files within each skill's directory:
+
+```
+~/.super-multica/skills/<skill-id>/.env
+```
+
+Example for the `earnings-analysis` skill:
+
+```bash
+# ~/.super-multica/skills/earnings-analysis/.env
+FINANCIAL_DATASETS_API_KEY=your-key-here
+```
+
+Skills declare their required environment variables in `SKILL.md` frontmatter:
+
+```yaml
+metadata:
+  requires:
+    env:
+      - FINANCIAL_DATASETS_API_KEY
+```
+
+The `.env` file is preserved across skill upgrades and is never committed to version control.
+
 ## LLM Providers
 
 **OAuth Providers** (external CLI login):
diff --git a/docs/product-capabilities.md b/docs/product-capabilities.md
index f79d7b75..99346456 100644
--- a/docs/product-capabilities.md
+++ b/docs/product-capabilities.md
@@ -744,7 +744,7 @@ Whitelisted devices reconnect without needing a new token or user confirmation.
 | File | Purpose | Permissions |
 |------|---------|-------------|
 | `~/.super-multica/credentials.json5` | LLM providers + tool API keys | 0o600 |
-| `~/.super-multica/skills.env.json5` | Skill/plugin environment variables | 0o600 |
+| `~/.super-multica/skills/<id>/.env` | Per-skill environment variables | 0o600 |
 
 Format: JSON5 (supports comments, trailing commas, unquoted keys).
 
@@ -771,23 +771,22 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).
 }
 ```
 
-#### 4.11.3 skills.env.json5 Structure
+#### 4.11.3 Per-Skill .env Files
 
-```json5
-{
-  env: {
-    LINEAR_API_KEY: "lin-...",
-    GITHUB_TOKEN: "ghp_...",
-  },
-}
+Each skill can have a `.env` file in its directory for API keys:
+
+```bash
+# ~/.super-multica/skills/earnings-analysis/.env
+FINANCIAL_DATASETS_API_KEY=your-key-here
 ```
 
+Skills declare required env vars in `SKILL.md` frontmatter under `metadata.requires.env`.
+
 #### 4.11.4 Environment Variable Overrides
 
 | Variable | Purpose |
 |----------|---------|
 | `SMC_CREDENTIALS_PATH` | Override credentials.json5 path |
-| `SMC_SKILLS_ENV_PATH` | Override skills.env.json5 path |
 | `SMC_CREDENTIALS_DISABLE=1` | Disable credentials loading |
 
 ---
@@ -1051,7 +1050,7 @@ button, input, textarea, card, dialog, alert-dialog, dropdown-menu, select, comb
 | Data | Location | Format | Lifetime |
 |------|----------|--------|----------|
 | Credentials | `~/.super-multica/credentials.json5` | JSON5 | User-managed |
-| Skills env | `~/.super-multica/skills.env.json5` | JSON5 | User-managed |
+| Skill API keys | `~/.super-multica/skills/<id>/.env` | dotenv | User-managed |
 | Agent profiles | `~/.super-multica/agent-profiles/{id}/` | MD + JSON | User-managed |
 | Agent memory | `~/.super-multica/agent-profiles/{id}/memory/` | JSON per key | Agent-managed |
 | Sessions | `~/.super-multica/sessions/{id}/session.jsonl` | JSONL | Until deleted |