# Security Principles for Using k-skill: A Complete Guide to Secrets Management and Safe Automation

> Learn k-skill security principles. Discover secrets management and safe automation techniques. Understand defense-in-depth for secure k-skill usage.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: how-to-guide
- Published: 2026-08-03

---

**k-skill enforces a defense-in-depth security model that prohibits hard-coded secrets, mandates environment-variable sourcing with standardized naming conventions, and requires user presence verification instead of bypassing authentication controls like CAPTCHAs.**

The **k-skill** framework from `NomaDamas/k-skill` implements rigorous security principles governing credentials, secrets, and sensitive data handling across its entire codebase. These principles are documented in [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md) and reinforced throughout the repository, creating a transparent and auditable security posture for all skill development.

## Zero Hard-Coded Secrets Policy

**Never hard-code secrets** stands as the foundational rule across the k-skill ecosystem. API keys, passwords, tokens, or any credential must never appear in source files, tests, or documentation according to the security policy.

All secrets are sourced exclusively from the environment at runtime. The repository maintains an explicit block-list of prohibited regex patterns that CI tests enforce automatically, ensuring no hard-coded token formats can be committed to the codebase.

## Centralized Credential Resolution

When a skill requires credentials, it follows a strict **credential resolution order** defined in [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md). This hierarchy ensures predictable and secure secret sourcing:

1. **Explicit environment variables** (e.g., `KSKILL_<SERVICE>_API_KEY`)
2. **User-wide secret store** located at `~/.config/k-skill/secrets.env`
3. **Free-API proxy fallback** when an upstream API requires an API key, as documented in [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md)

The README highlights this workflow at line 171 and provides a summary table of secret policies at line 183, ensuring developers understand the precedence rules before writing code.

## Standardized Environment Variable Naming

All secret-related environment variables obey a common **`KSKILL_`** prefix and use snake-case formatting. This standardization makes scanning for accidental leaks trivial and ensures consistency across all packages in the monorepo.

For example, a service named `example` would use `KSKILL_EXAMPLE_API_KEY`, while public data services might use `KSKILL_PUBLICDATA_API_KEY`.

## Runtime Secret Handling Workflow

The framework implements a **strict secret-handling workflow** designed to minimize exposure:

- Secrets are read **once** at startup and stored only in memory
- They are never logged, printed, or written back to disk
- When a skill terminates, any in-memory references are explicitly cleared

This approach ensures that sensitive data exists only transiently during execution and leaves no residual traces in system logs or crash dumps.

## Authentication Bypass Prohibitions

Skills are strictly prohibited from automating or circumventing authentication mechanisms such as CAPTCHAs, login pages, certificates, or payment flows. The [`packages/k-skill-cli/templates/legal.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/templates/legal.md) file explicitly states that automation must stop at the point where user-presence verification is required.

When encountering security checkpoints, skills must hand control back to the user rather than attempting automated circumvention:

```javascript
if (await page.isCaptchaPresent()) {
  // Do not attempt to solve the CAPTCHA automatically.
  // Hand control back to the user with a clear message.
  await requestUserAction("Please solve the CAPTCHA manually.");
  return;
}

```

## Proxy Usage Policies

The built-in **k-skill-proxy** is used exclusively for free APIs that require an API key. Public, unauthenticated endpoints are called directly from the client to avoid unnecessary routing and credential exposure, as specified in [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md).

This architectural decision minimizes the attack surface by ensuring the proxy server handles only authenticated traffic that would otherwise require key management, while direct public API calls bypass the proxy infrastructure entirely.

## Dependency Security Management

The `k-skill-proxy` package maintains rigorous dependency hygiene. According to [`packages/k-skill-proxy/CHANGELOG.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/CHANGELOG.md), the team regularly upgrades Fastify and other third-party libraries to incorporate upstream security fixes, ensuring that the proxy infrastructure itself remains hardened against known vulnerabilities.

## Practical Implementation Examples

### Loading Secrets from Environment Variables

Python skills should follow this pattern for secure credential access:

```python
import os

API_KEY = os.getenv("KSKILL_EXAMPLE_API_KEY")
if not API_KEY:
    raise RuntimeError("Missing required API key: KSKILL_EXAMPLE_API_KEY")

# Use API_KEY only in memory – never log or write it out

response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

```

### Using the Free-API Proxy

Node.js skills requiring authenticated public APIs should route through the proxy:

```javascript
// In a k-skill-cli skill script
import { fetchViaProxy } from "k-skill-proxy";

const apiKey = process.env.KSKILL_PUBLICDATA_API_KEY; // env-only
const result = await fetchViaProxy(
  "https://publicdata.example.com/v1/resource",
  { headers: { "x-api-key": apiKey } }
);

```

## Summary

- **Never commit secrets**: All credentials must reside in environment variables or the user-wide secret store at `~/.config/k-skill/secrets.env`, never in source code
- **Follow the resolution order**: Check explicit env vars first, then the secrets file, then the proxy fallback
- **Use standardized naming**: Prefix all skill secrets with `KSKILL_` and use snake_case for consistency
- **Respect security boundaries**: Stop automation at CAPTCHAs, login screens, and payment flows; never attempt to bypass authentication
- **Proxy selectively**: Route only authenticated free APIs through `k-skill-proxy`; call public endpoints directly
- **Clear memory**: Store secrets only in memory, never log them, and clear references on termination

## Frequently Asked Questions

### How does k-skill handle API keys and secrets?

k-skill requires all API keys and secrets to be sourced from environment variables or a user-wide secret store at `~/.config/k-skill/secrets.env`. According to [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md), credentials are read once at startup, stored only in memory, and never logged or written to disk. This ensures secrets never appear in source code or version control.

### What is the credential resolution order in k-skill?

The credential resolution order follows a strict hierarchy defined in [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md): first explicit environment variables (e.g., `KSKILL_SERVICE_API_KEY`), second the user-wide secret store, and third the free-API proxy fallback for authenticated endpoints. The README at lines 171 and 183 provides a quick reference table summarizing this precedence for developers.

### Are developers allowed to automate CAPTCHA solving in k-skill skills?

No. The security principles explicitly prohibit bypassing authentication controls including CAPTCHAs, login pages, and payment flows. As documented in [`packages/k-skill-cli/templates/legal.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/templates/legal.md), skills must stop automation and request manual user action when encountering security checkpoints that require human verification.

### When should I use the k-skill-proxy versus direct API calls?

Use **k-skill-proxy** exclusively for free APIs that require an API key, as specified in [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md). Public, unauthenticated endpoints should be called directly from the client to minimize routing overhead and reduce credential exposure. The proxy serves only as a fallback for authenticated public services that would otherwise require key management.