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

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 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. 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

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 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:

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.

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, 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:

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:

// 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, 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: 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, 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. 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.

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