How to Troubleshoot k-skill Installation: 8-Step Diagnostic Guide

To troubleshoot k-skill installation, verify Node.js 18+ and npx are available, refresh the skill catalog with --list, install the full skill set with -g, run k-skill-setup to finalize credentials, then test with a simple skill like zipcode-search.

The k-skill monorepo from NomaDamas delivers a large collection of command-line skills via an npm workspace architecture. Understanding this three-layer structure—documentation-driven metadata, workspace packages, and runtime CLI—is essential when installation issues arise. This guide walks through common failure points and provides a precise troubleshooting workflow based on the official source code.

Core Architecture of k-skill

k-skill is organized into three distinct layers that each affect installation behavior.

Documentation Layer (docs/)

The docs/ directory contains the canonical installation guides that drive the expected flow. Key files include:

• docs/install.md — Primary installation guide with exact CLI commands
• docs/install-manus.md — Alternative workflow for Manus.ai installations
• docs/setup.md — Details the k-skill-setup skill for finalizing credentials
• docs/security-and-secrets.md — Required secret names and storage locations
• docs/features/k-skill-proxy.md — Hosted proxy documentation for network-dependent skills

These files define the official process and should be your first reference when verifying steps.

Workspace Packages (packages/)

Each skill's source files (SKILL.md, scripts/, references/) are packaged as npm workspaces. The CLI assembles the final instruction set at runtime by pulling relevant SKILL.md files together. This means skill definitions are resolved dynamically rather than being statically installed.

Runtime CLI (k-skill command)

The CLI is a thin wrapper that delegates to npx -y @nomadamas/k-skill@0. It automatically resolves the correct package version, reads skill definitions, and executes helper scripts—so the CLI itself never needs a separate installation.

Common Installation Failures and Fixes

"Command not found" or npx errors

Likely cause: Node.js 18+ or npm is missing.

Diagnostic steps:

node -v
npm -v

If either command fails, install Node.js 18+ from https://nodejs.org.

"Skill not found" after skills add

Likely cause: Using an outdated skill list or missing the --list flag.

Fix: Refresh the catalog explicitly:

npx --yes skills add NomaDamas/k-skill --list

As documented in docs/install.md lines 24-30, the --list flag is required to update the local skill index.

Helper script crashes (Python/Node errors)

Likely cause: Missing global dependencies for specific languages.

Python dependencies:

python3 -m pip install SRTrain korail2 pycryptodome

Node dependencies:

npm install -g kordoc pdfjs-dist

Refer to the language-specific sections in docs/install.md for your operating system.

API errors (401, 403)

Likely cause: Secrets not supplied or proxy misconfiguration.

Fix: Verify environment variables in ~/.config/k-skill/secrets.env or system PATH as described in docs/security-and-secrets.md (lines 89-92 in install.md).

"Unable to locate skill" after partial installation

Likely cause: Skipping the common setup step.

Fix: Always run the setup skill after any installation:

k-skill-setup

Alternatively: npx -y @nomadamas/k-skill@0 exec k-skill-setup

Step-by-Step Troubleshooting Workflow

Follow this verified sequence from the official documentation:

# 1. Verify Node and npx availability

node -v && npx -v

# 2. Refresh the skill catalog

npx --yes skills add NomaDamas/k-skill --list

# 3. Install the full skill set (recommended)

npx --yes skills add NomaDamas/k-skill --all -g

# 4. Run the common setup skill

k-skill-setup

# 5. Test a simple skill

npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- --help

# 6. Check proxy health if needed

curl -fsS https://k-skill-proxy.nomadamas.org/health

If step 5 fails, inspect ~/.config/k-skill/secrets.env against docs/security-and-secrets.md. Any deviation from this order—such as omitting --list or skipping k-skill-setup—is a documented cause of installation failures.

Key Files for Troubleshooting

File	Purpose
docs/install.md	Primary installation guide; defines exact CLI commands and operation order
docs/install-manus.md	Manus.ai-specific installation workflow
docs/setup.md	k-skill-setup skill documentation for credential finalization
docs/security-and-secrets.md	Required secret names and storage locations
docs/features/k-skill-proxy.md	Hosted proxy troubleshooting for network-dependent skills
SKILL.md (per-skill)	Front-matter and command list for verifying skill entry points

Summary

• k-skill uses a three-layer architecture: documentation metadata, npm workspace packages, and a thin npx-based CLI
• Always verify Node.js 18+ and npx before attempting installation
• Use --list to refresh the skill catalog and -g for global installation
• Run k-skill-setup after any installation to finalize credentials and environment variables
• Check ~/.config/k-skill/secrets.env and docs/security-and-secrets.md for API authentication issues
• Consult per-skill SKILL.md files to verify expected command entry points

Frequently Asked Questions

Why does k-skill require Node.js 18 or higher?

The runtime CLI relies on modern npm features and npx behavior that are only stable in Node.js 18+. Earlier versions may fail to resolve workspace packages correctly or handle the --yes flag as expected.

What is the difference between skills add and k-skill-setup?

skills add downloads and registers skill definitions from the NomaDamas/k-skill repository. k-skill-setup is a separate skill that configures credentials, environment variables, and finalizes the installation—skipping it leaves the environment in an incomplete state.

Where should I store API secrets for k-skill skills?

Secrets belong in ~/.config/k-skill/secrets.env or as environment variables in your system PATH. The exact variable names required for each skill are documented in docs/security-and-secrets.md.

How do I verify that a specific skill is properly installed?

Test execution with a simple command structure: npx -y @nomadamas/k-skill@0 exec <skill-name> scripts/<script> -- --help. Check the skill's SKILL.md file to confirm the correct script paths and required arguments.

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