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

> Troubleshoot k-skill installation with this 8-step guide. Verify Node.js, refresh catalog, install fully, set up credentials, and test with simple skills for a successful setup.

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

---

**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`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) — Primary installation guide with exact CLI commands
- [`docs/install-manus.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install-manus.md) — Alternative workflow for Manus.ai installations
- [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md) — Details the `k-skill-setup` skill for finalizing credentials
- [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md) — Required secret names and storage locations
- [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md), `scripts/`, `references/`) are packaged as npm workspaces. The CLI assembles the final instruction set at runtime by pulling relevant [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/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:**

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

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

```

As documented in [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/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:**

```bash
python3 -m pip install SRTrain korail2 pycryptodome

```

**Node dependencies:**

```bash
npm install -g kordoc pdfjs-dist

```

Refer to the language-specific sections in [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md) (lines 89-92 in [`install.md`](https://github.com/NomaDamas/k-skill/blob/main/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:

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

```bash

# 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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) | Primary installation guide; defines exact CLI commands and operation order |
| [`docs/install-manus.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install-manus.md) | Manus.ai-specific installation workflow |
| [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md) | `k-skill-setup` skill documentation for credential finalization |
| [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md) | Required secret names and storage locations |
| [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md) | Hosted proxy troubleshooting for network-dependent skills |
| [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md)** for API authentication issues
- Consult per-skill **[`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) file to confirm the correct script paths and required arguments.