How to Configure k-skill: Complete Setup Guide for the Workspace-Based Skill System

k-skill configuration requires bootstrapping the CLI, generating skill stubs from skill.json manifests, and setting up a secure ~/.config/k-skill/secrets.env file with API credentials.

k-skill is a modular, workspace-based system developed by NomaDamas that combines a CLI front-end, autonomous skill packages, and an optional proxy server for free-API access. Understanding how to configure k-skill properly ensures your skills can resolve credentials, route requests, and execute across multiple runtimes without hard-coded secrets.

Configuration Architecture Overview

k-skill organizes configuration across three distinct layers. Each layer has specific responsibilities, file locations, and key settings.

Layer 1: CLI/Runtime Configuration

The CLI layer boots the skill system, discovers installed skills, and forwards requests to the appropriate runtime (Node.js, Python, or browser).

Aspect	Details
Location	packages/k-skill-cli/ — the core CLI package
Bootstrap	npm install at repository root
Regeneration	Run npm run generate:skill-stubs after editing skill.json or instruction.md
Guidelines	Follow Unified CLI skill instruction rules in AGENTS.md

Layer 2: Skill Definitions

Each autonomous capability lives in its own folder with standardized files.

File	Purpose
skill.json	Declares skill name, profile, required environment variables, and runtime
instruction.md	Describes inputs, outputs, and external service requirements
scripts/	Optional folder for custom execution logic (e.g., zipcode-search/scripts/zipcode_search.py)

Example: zipcode-search/skill.json defines the postal code lookup capability.

Layer 3: Credential and Proxy Configuration

Secrets follow a strict three-level precedence system:

1. Already-injected environment variables (highest priority)
2. Host vault (Dolshoi) for enterprise deployments
3. Local dotenv file ~/.config/k-skill/secrets.env with mode 0600 (default for standalone setups)

The proxy server at packages/k-skill-proxy/src/server.js forwards requests requiring API keys and returns 503 upstream_not_configured when a key is missing.

Step-by-Step k-skill Configuration Workflow

1. Bootstrap the CLI and Workspace

After cloning the repository, install all workspace packages:

git clone https://github.com/NomaDamas/k-skill.git
cd k-skill
npm install

This creates the node_modules hierarchy across packages/*.

2. Generate and Sync Skill Stubs

Whenever you modify skill.json or instruction.md, regenerate the CLI adapters:

npm run generate:skill-stubs
npm run sync:cli-skills

The sync:cli-skills command copies top-level skill definitions into packages/k-skill-cli/skills/.

3. Create the Secrets File

Use the built-in k-skill-setup skill for first-time credential configuration:

npx -y @nomadamas/k-skill@0 exec k-skill-setup scripts/setup.sh -- config-check

This command:

• Creates ~/.config/k-skill/secrets.env if absent
• Sets file mode to 0600 (owner read/write only)
• Prompts for required API keys

Alternatively, create the file manually:

mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
DATA_GO_KR_API_KEY=YOUR_DATA_GO_KEY
NAVER_SEARCH_CLIENT_ID=YOUR_NAVER_ID
NAVER_SEARCH_CLIENT_SECRET=YOUR_NAVER_SECRET
KAKAO_REST_API_KEY=YOUR_KAKAO_KEY
EOF
chmod 600 ~/.config/k-skill/secrets.env

4. Export Required Environment Variables

Add entries for any skill needing external API access:

echo "DATA_GO_KR_API_KEY=your-key-here" >> ~/.config/k-skill/secrets.env

Each skill's skill.json declares its required environment variables.

5. Start the Proxy Server (Optional)

For free-API routes requiring key management, caching, or rate-limiting:

node packages/k-skill-proxy/src/server.js

The proxy:

• Reads credentials from the same secrets file
• Exposes routes under http://localhost:3000/v1/...
• Returns 503 upstream_not_configured for missing keys

Enable a route by setting its associated environment variable (e.g., NAVER_SEARCH_CLIENT_ID). Reference the proxy README at packages/k-skill-proxy/README.md for route-specific configuration.

6. Execute Skills

Run a skill through the CLI:

npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- "서울 강남구"

The CLI resolves credentials from the secrets file, contacts the appropriate endpoint (direct or via proxy), and returns results.

Key Configuration Files Reference

File Path	Role
packages/k-skill-cli/	Core CLI implementation for skill discovery and command routing
packages/k-skill-proxy/src/server.js	Proxy server with API-key handling, caching, and rate-limiting
k-skill-setup/skill.json	Setup skill definition that automates secrets file creation
*/skill.json (e.g., zipcode-search/skill.json)	Per-skill manifest with environment variable requirements
*/instruction.md	Human-readable skill specifications
~/.config/k-skill/secrets.env	Secure local credential store (mode 0600 required)
AGENTS.md	Repository-wide CLI generation and release guidelines
.github/workflows/ci.yml	CI pipeline running npm run ci for package verification

Summary

• k-skill configuration spans three layers: CLI/runtime, skill definitions, and credential management
• Bootstrap with npm install, then regenerate stubs with npm run generate:skill-stubs after any skill.json changes
• Store secrets exclusively in ~/.config/k-skill/secrets.env with chmod 600 permissions—never hard-code API keys
• Use the k-skill-setup skill or manual creation to initialize credential storage
• Enable proxy routes by setting corresponding environment variables; the proxy returns 503 upstream_not_configured for unconfigured services
• Reference skill manifests at skill.json to identify required environment variables per capability

Frequently Asked Questions

Where does k-skill store API credentials?

k-skill searches for credentials in three locations, in order: (1) already-injected environment variables, (2) the host vault (Dolshoi) for enterprise setups, and (3) the local file ~/.config/k-skill/secrets.env. The local file must have mode 0600 and is created automatically by the k-skill-setup skill.

How do I regenerate CLI adapters after modifying a skill?

Run npm run generate:skill-stubs to update generated adapters, then npm run sync:cli-skills to copy skill definitions into packages/k-skill-cli/skills/. These commands are defined in the root package.json and documented in AGENTS.md.

What happens if the proxy server cannot find an API key?

The proxy at packages/k-skill-proxy/src/server.js returns HTTP 503 upstream_not_configured when a requested route requires an API key that is not set in the environment or secrets file. Check the specific skill's skill.json for required variable names.

Can I run k-skill without the proxy server?

Yes. The proxy is optional and only required for skills that need free-API access with key management, caching, or rate-limiting. Direct API calls from skills work when credentials are available through environment variables or the secrets file.

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