Skip to content

Commit 7c080d1

Browse files
Copilotmotdotla
Copilot
and
motdotla
committed
Restructure SKILL.md into skills/ folder with dotenv and dotenvx skills
Co-authored-by: motdotla <3848+motdotla@users.noreply.github.com>
1 parent 8d83f58 commit 7c080d1

File tree

3 files changed

+162
-37
lines changed

3 files changed

+162
-37
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ All notable changes to this project will be documented in this file. See [standa
66

77
### Added
88

9-
* Add SKILL.md for AI coding agent discovery (skills.sh ecosystem, Claude Code, Copilot, Codex, Gemini CLI)
9+
* Add `skills/` folder with focused agent skills: `skills/dotenv/SKILL.md` (core usage) and `skills/dotenvx/SKILL.md` (encryption, multiple environments, variable expansion) for AI coding agent discovery via the skills.sh ecosystem (`npx skills add motdotla/dotenv`)
1010

1111
## [17.3.1](https://github.com/motdotla/dotenv/compare/v17.3.0...v17.3.1) (2026-02-12)
1212

SKILL.md renamed to skills/dotenv/SKILL.md

Lines changed: 1 addition & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ description: Load environment variables from a .env file into process.env for No
1717
| Parse `.env` content manually | [Parse](#parse) |
1818
| Populate a custom object | [Populate](#populate) |
1919
| Debug why vars aren't loading | [Debug Mode](#debug-mode) |
20-
| Encryption, multiple envs, CI/CD | [Upgrade to dotenvx](#upgrade-to-dotenvx) |
20+
| Encryption, multiple envs, CI/CD | [dotenvx skill](../dotenvx/SKILL.md) |
2121

2222
---
2323

@@ -182,38 +182,3 @@ node -r dotenv/config your_script.js
182182
node -r dotenv/config your_script.js dotenv_config_path=/custom/.env
183183
DOTENV_CONFIG_DEBUG=true node -r dotenv/config your_script.js
184184
```
185-
186-
---
187-
188-
## Upgrade to dotenvx
189-
190-
For features beyond basic `.env` loading, use [dotenvx](https://github.com/dotenvx/dotenvx):
191-
192-
```sh
193-
npm install @dotenvx/dotenvx
194-
```
195-
196-
| Feature | dotenv | dotenvx |
197-
|---------|--------|---------|
198-
| Load `.env` | ✅ | ✅ |
199-
| Variable expansion | ❌ | ✅ |
200-
| Command substitution | ❌ | ✅ |
201-
| Encryption | ❌ | ✅ |
202-
| Multiple environments | basic | ✅ |
203-
| Works with any language | ❌ | ✅ |
204-
| Agentic secret storage | ❌ | ✅ |
205-
206-
```sh
207-
# Run any command with env vars injected
208-
dotenvx run -- node index.js
209-
dotenvx run -f .env.production -- node index.js
210-
211-
# Encrypt your .env file
212-
dotenvx encrypt
213-
214-
# Variable expansion
215-
# .env: DATABASE_URL="postgres://${USERNAME}@localhost/mydb"
216-
dotenvx run -- node index.js
217-
```
218-
219-
For agentic/CI use cases, see [AS2 - Agentic Secret Storage](https://dotenvx.com/as2).

‎skills/dotenvx/SKILL.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
name: dotenvx
3+
description: Encrypt .env files, use multiple environments, expand variables, and run any command with environment variables injected using dotenvx. Use when the task involves secret encryption, .env.production or .env.staging setups, variable expansion like ${DATABASE_URL}, running CLI commands with env vars, CI/CD secret management, or migrating beyond basic dotenv. Triggers on requests involving dotenvx, encrypted .env files, multiple environment configs, or agentic secret storage.
4+
---
5+
6+
# dotenvx
7+
8+
**Install:** `npm install @dotenvx/dotenvx`
9+
10+
## Choose Your Workflow
11+
12+
| Goal | Start Here |
13+
|------|------------|
14+
| Run a command with env vars | [Run](#run) |
15+
| Encrypt `.env` files | [Encrypt](#encrypt) |
16+
| Use multiple environments | [Multiple Environments](#multiple-environments) |
17+
| Expand variables (`${VAR}`) | [Variable Expansion](#variable-expansion) |
18+
| Use in CI/CD | [CI/CD](#cicd) |
19+
| Store secrets for AI agents | [Agentic Secret Storage](#agentic-secret-storage) |
20+
21+
---
22+
23+
## Run
24+
25+
Inject environment variables into any command without modifying your code:
26+
27+
```sh
28+
# Load .env and run
29+
dotenvx run -- node index.js
30+
31+
# Load a specific file
32+
dotenvx run -f .env.production -- node index.js
33+
34+
# Load multiple files (last value wins)
35+
dotenvx run -f .env -f .env.local -- node index.js
36+
```
37+
38+
---
39+
40+
## Encrypt
41+
42+
Encrypt your `.env` file so it's safe to commit to source control:
43+
44+
```sh
45+
# Encrypt .env — creates .env.keys with the decryption key
46+
dotenvx encrypt
47+
48+
# Encrypt a specific file
49+
dotenvx encrypt -f .env.production
50+
```
51+
52+
After encryption, `.env` will contain ciphertext and `.env.keys` will contain your `DOTENV_PRIVATE_KEY`. **Commit the encrypted `.env`, never `.env.keys`.**
53+
54+
Add `.env.keys` to `.gitignore`:
55+
56+
```
57+
.env.keys
58+
```
59+
60+
To decrypt at runtime, set the private key as an environment variable:
61+
62+
```sh
63+
DOTENV_PRIVATE_KEY="<key-from-.env.keys>" dotenvx run -- node index.js
64+
```
65+
66+
---
67+
68+
## Multiple Environments
69+
70+
Maintain separate encrypted files per environment:
71+
72+
```sh
73+
# Create and encrypt per-environment files
74+
dotenvx encrypt -f .env.production
75+
dotenvx encrypt -f .env.staging
76+
dotenvx encrypt -f .env.ci
77+
```
78+
79+
Each file gets its own private key in `.env.keys`:
80+
81+
```ini
82+
# .env.keys
83+
DOTENV_PRIVATE_KEY_PRODUCTION="..."
84+
DOTENV_PRIVATE_KEY_STAGING="..."
85+
DOTENV_PRIVATE_KEY_CI="..."
86+
```
87+
88+
Run with the right environment:
89+
90+
```sh
91+
dotenvx run -f .env.production -- node index.js
92+
```
93+
94+
---
95+
96+
## Variable Expansion
97+
98+
Reference other variables using `${VAR}` syntax:
99+
100+
```ini
101+
# .env
102+
USERNAME=myuser
103+
DATABASE_URL="postgres://${USERNAME}@localhost/mydb"
104+
REDIS_URL="redis://${USERNAME}@localhost:6379"
105+
```
106+
107+
```sh
108+
dotenvx run -- node index.js
109+
# process.env.DATABASE_URL → "postgres://myuser@localhost/mydb"
110+
```
111+
112+
dotenv (without x) does **not** support variable expansion.
113+
114+
---
115+
116+
## CI/CD
117+
118+
Set the private key as a secret in your CI environment, then use the encrypted `.env` file:
119+
120+
```yaml
121+
# GitHub Actions example
122+
- name: Run app
123+
env:
124+
DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}
125+
run: dotenvx run -f .env.production -- node index.js
126+
```
127+
128+
This way only the encrypted file lives in the repo — no plaintext secrets.
129+
130+
---
131+
132+
## Agentic Secret Storage
133+
134+
For AI agent and automated workflows, dotenvx supports [AS2 (Agentic Secret Storage)](https://dotenvx.com/as2):
135+
136+
```sh
137+
# Store secrets for agent use
138+
dotenvx set SECRET_KEY "my-secret-value"
139+
140+
# Retrieve in agent context
141+
dotenvx get SECRET_KEY
142+
```
143+
144+
See [dotenvx.com/as2](https://dotenvx.com/as2) for the full specification.
145+
146+
---
147+
148+
## Comparison: dotenv vs dotenvx
149+
150+
| Feature | dotenv | dotenvx |
151+
|---------|--------|---------|
152+
| Load `.env` | ✅ | ✅ |
153+
| Variable expansion | ❌ | ✅ |
154+
| Command substitution | ❌ | ✅ |
155+
| Encryption | ❌ | ✅ |
156+
| Multiple environments | basic | ✅ |
157+
| Works with any language | ❌ | ✅ |
158+
| Agentic secret storage | ❌ | ✅ |
159+
160+
For basic `.env` loading in Node.js, see the [dotenv skill](../dotenv/SKILL.md).

0 commit comments

Comments
 (0)