k-skill Secrets File Format: Complete Configuration Guide

The k-skill secrets file uses a plain-text .env-style format consisting of one KEY=VALUE pair per line, supporting hash-prefixed comments, blank lines, and optional double-quoting for values containing spaces or special characters.

The k-skill repository by NomaDamas stores sensitive configuration data—such as API keys and provider tokens—in a dedicated secrets file that follows standard dotenv conventions. Understanding the exact syntax and loading mechanisms ensures that credentials remain secure while remaining accessible to both Python and Node.js skill components at runtime.

Standard File Location

By default, k-skill expects the secrets file at ~/.config/k-skill/secrets.env. You can verify the expected structure and available configuration keys by examining the reference example at examples/secrets.env.example in the repository root.

Syntax and Structure Rules

The file format is straightforward and human-readable:

• One entry per line using KEY=VALUE syntax
• No export keyword required (unlike standard shell scripts)
• Keys are conventionally uppercase with underscores

Comments and Blank Lines

Lines beginning with # are treated as comments and ignored by the loader. Blank lines are also permitted and ignored, which helps organize the file into logical sections for different service categories.

Value Quoting

Simple string values require no quotes. However, if a value contains spaces or special characters, wrap it in double quotes to ensure correct parsing:

SIMPLE_KEY=value
QUOTED_KEY="value with spaces"

Example Configuration

A complete secrets file for k-skill typically includes the following variables as demonstrated in the repository example:

# k-skill secrets configuration

KSKILL_PROXY_API_KEY=your-proxy-api-key
KSKILL_BROWSER_PROVIDER=auto
CLOAKBROWSER_PEEK_TOKEN=your-peek-token

# Optional: custom endpoint overrides

CUSTOM_API_ENDPOINT="https://api.example.com/v1"

Loading the Secrets File

The repository uses standard dotenv loaders to inject these values into the process environment at runtime.

Python Implementation

In Python skills, the python-dotenv library loads the secrets from the default location:

from pathlib import Path
from dotenv import load_dotenv
import os

# Load the default secrets file

secrets_path = Path.home() / ".config" / "k-skill" / "secrets.env"
load_dotenv(secrets_path)

# Access a secret

proxy_key = os.getenv("KSKILL_PROXY_API_KEY")

Node.js Implementation

For Node.js components such as the proxy server, the dotenv package handles the loading:

const path = require('path');
require('dotenv').config({
  path: path.join(process.env.HOME, '.config', 'k-skill', 'secrets.env')
});

const proxyKey = process.env.KSKILL_PROXY_API_KEY;

Customizing the Secrets Path

You can override the default file location by setting the KSKILL_SECRETS_PATH environment variable before launching the skill:

export KSKILL_SECRETS_PATH=/my/custom/secrets.env

This flexibility allows deployment scripts like [scripts/deploy-k-skill-proxy-gpu01.sh](https://github.com/NomaDamas/k-skill/blob/main/scripts/deploy-k-skill-proxy-gpu01.sh) to specify alternative paths for different environments without modifying code.

Integration with k-skill-proxy

The proxy server implementation in [packages/k-skill-proxy/src/server.js](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) reads these environment variables at startup to authenticate with external providers. Because both Python and Node.js implementations respect the same KEY=VALUE syntax, secrets files are fully interchangeable between runtime environments.

Summary

• The k-skill secrets file follows standard .env format with KEY=VALUE pairs and optional double quotes
• Store the file at ~/.config/k-skill/secrets.env by default, or override with the KSKILL_SECRETS_PATH environment variable
• Use # for comments and blank lines for readability; never include the export keyword
• Load via python-dotenv in Python or dotenv in Node.js according to the repository patterns
• Reference examples/secrets.env.example for the complete list of supported configuration keys

Frequently Asked Questions

Does the k-skill secrets file require the export keyword?

No. Unlike shell scripts where you might write export KEY=value, the k-skill secrets file should contain only KEY=value pairs. The dotenv loaders used throughout the repository automatically handle environment variable assignment without the export prefix, keeping the file compatible with both Python and Node.js parsers.

Can I use single quotes instead of double quotes for values?

The standard format allows optional double quotes for values containing spaces or special characters. While some dotenv parsers accept single quotes, the k-skill repository examples and deployment scripts consistently use double quotes or unquoted values, making double quotes the recommended choice for consistency across the codebase.

What happens if I move the secrets file to a non-standard location?

The runtime will fail to locate the secrets unless you set the KSKILL_SECRETS_PATH environment variable to point to the new location. Both Python and Node.js implementations check this variable before defaulting to ~/.config/k-skill/secrets.env, allowing flexible deployment configurations.

Are blank lines allowed in the middle of the file?

Yes. Blank lines are ignored by the parser and can be used to visually separate logical groups of configuration variables, such as grouping all browser-related tokens separately from API endpoint overrides, without affecting runtime behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}