# How to Generate Skill Stubs with k-skill-cli: A Complete Guide

> Learn to generate skill stubs using k-skill-cli with our complete guide. Easily scaffold new skill directories with essential files and templates. Run the generate skill stubs command now.

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

---

**Run `npm run generate:skill-stubs` with the `--name`, `--description`, and `--profiles` flags to scaffold a new skill directory complete with [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), and template files.**

The **k-skill-cli** package in the `NomaDamas/k-skill` repository provides a command-line interface for managing executable skill instructions. When you need to add a new capability to the system, you don't need to create files manually—the CLI includes a scaffolding script that generates fully-structured **skill stubs** following the repository's architectural standards.

## What Are Skill Stubs?

A **skill stub** is the foundational directory structure for a new skill. It includes the declarative metadata, instruction templates, and optional script placeholders required for the `k-skill` toolchain to assemble and execute runtime instructions. Because the generation process copies from the canonical templates in `packages/k-skill-cli/templates/`, every stub you create maintains architectural parity with existing skills in the repository.

## Prerequisites

Before generating stubs, ensure you have the repository cloned and dependencies installed:

```bash
npm install

```

This installs the workspace dependencies required by the scaffolding script located at [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js).

## Generating a New Skill Stub

The generation workflow is driven by the **`generate:skill-stubs`** npm script. This script handles prompting, template copying, and index registration automatically.

### Run the Scaffold Command

Execute the generator with the required parameters:

```bash
npm run generate:skill-stubs -- \
  --name my-awesome-skill \
  --description "Demo skill that shows how to scaffold a stub" \
  --profiles lookup,action-booking

```

The `--profiles` flag specifies which template fragments (from `packages/k-skill-cli/templates/`) your skill supports. Common options include `lookup`, `action-booking`, and `core`.

### Verify the Generated Structure

Upon completion, the CLI creates a new directory at `packages/k-skill-cli/skills/<your-skill>/`:

```bash
tree packages/k-skill-cli/skills/my-awesome-skill

```

Expected output:

```

├── instruction.md
├── skill.json
└── scripts/          # empty – add your helper scripts here

```

## Understanding the Generated Files

The scaffold creates three essential components that make your skill discoverable and executable.

### skill.json Metadata

The **[`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json)** file contains the skill name, description, supported profiles list, and optional front-matter values. This file is parsed by the CLI entry point at [`packages/k-skill-cli/bin/k-skill.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/bin/k-skill.js) to populate the skills index.

Example structure:

```json
{
  "name": "my-awesome-skill",
  "description": "Demo skill that shows how to scaffold a stub",
  "profiles": ["lookup", "action-booking"]
}

```

### instruction.md

The **[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)** file serves as the human-readable instruction document. During runtime, the assembler in [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js) merges this file with profile-specific templates (such as [`core.md`](https://github.com/NomaDamas/k-skill/blob/main/core.md) or [`lookup.md`](https://github.com/NomaDamas/k-skill/blob/main/lookup.md)) to produce the final executable instructions.

### The scripts Directory

The **`scripts/`** folder is optional and initially empty. You can populate it with executable helpers written in Python, JavaScript, or shell scripts. These scripts can be invoked later using the `k-skill exec` command.

## Working with Your New Skill

Once generated, your skill is immediately integrated with the CLI toolchain.

### Listing the Skill

Verify registration by listing all available skills:

```bash
npx k-skill list | grep my-awesome-skill

```

Output:

```

my-awesome-skill

```

The new skill automatically participates in the assemble pipeline because the scaffolding script updates the CLI index.

### Assembling Instructions

Preview the assembled runtime instructions:

```bash
npx k-skill instruct my-awesome-skill

```

This command invokes the assembler logic from [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js), which processes your [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) along with the profile templates specified during generation.

### Executing Helper Scripts

After adding scripts to the `scripts/` directory, execute them with:

```bash
npx k-skill exec my-awesome-skill scripts/do_work.py -- arg1 arg2

```

The `exec` command, implemented in [`packages/k-skill-cli/bin/k-skill.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/bin/k-skill.js), handles runtime detection and script execution across different environments (Dolshoi, CloakBrowser, or local).

## How the Scaffolding Works Under the Hood

The **`generate:skill-stubs`** script defined in the root [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) internally invokes `node scripts/generate-skill-stubs.js`. This script performs four critical operations:

1. **Prompts for metadata** – captures name, description, and profile selections.
2. **Copies templates** – replicates files from `packages/k-skill-cli/templates/` (including [`core.md`](https://github.com/NomaDamas/k-skill/blob/main/core.md), [`lookup.md`](https://github.com/NomaDamas/k-skill/blob/main/lookup.md), and [`action-booking.md`](https://github.com/NomaDamas/k-skill/blob/main/action-booking.md)) into the new skill directory.
3. **Writes configuration** – generates [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) with the provided metadata.
4. **Updates the index** – registers the skill so it becomes discoverable via the `list` command and available to the `instruct` pipeline.

Because the stub generation uses the same template files that power all existing skills, architectural consistency is guaranteed. The actual runtime detection (determining whether to run on Dolshoi, CloakBrowser, or locally) is handled later by the `k-skill` command when you invoke the skill, keeping the stub itself runtime-agnostic.

## Summary

- **Use `npm run generate:skill-stubs`** with `--name`, `--description`, and `--profiles` to create new skills.
- **Generated stubs** include [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), and an optional `scripts/` directory at `packages/k-skill-cli/skills/<skill>/`.
- **Template files** are copied from `packages/k-skill-cli/templates/` to ensure architectural consistency.
- **Immediate availability** – new skills are automatically indexed and accessible via `npx k-skill list` and `npx k-skill instruct`.
- **Runtime-agnostic** – stubs contain only declarative metadata; execution environments are determined at runtime.

## Frequently Asked Questions

### What profiles can I specify when generating a skill stub?

The `--profiles` flag accepts a comma-separated list of template names available in `packages/k-skill-cli/templates/`. Common values include `lookup`, `action-booking`, and `core`. These determine which Markdown fragment templates are copied into your skill's directory and later merged by the assembler.

### Where are the template files located in the repository?

Template files reside in `packages/k-skill-cli/templates/` and include fragments like [`core.md`](https://github.com/NomaDamas/k-skill/blob/main/core.md), [`lookup.md`](https://github.com/NomaDamas/k-skill/blob/main/lookup.md), and [`action-booking.md`](https://github.com/NomaDamas/k-skill/blob/main/action-booking.md). The scaffolding script copies these files into your new skill directory during generation, ensuring your stub uses the same structural components as existing skills.

### Can I use custom scripts with my generated skill stub?

Yes. After generation, place executable files (Python, JavaScript, or shell scripts) in the `scripts/` directory of your skill. You can then execute them using `npx k-skill exec <skill-name> scripts/<filename> -- <arguments>`. The CLI handles cross-platform execution and runtime environment detection automatically.

### How do I make my new skill available to the k-skill CLI commands?

The scaffolding script automatically updates the CLI index when you run `generate:skill-stubs`. Your skill becomes immediately discoverable via `npx k-skill list` and can be used with `npx k-skill instruct <skill>` without additional configuration. The [`packages/k-skill-cli/bin/k-skill.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/bin/k-skill.js) entry point reads the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files from all subdirectories in `packages/k-skill-cli/skills/` to build the available commands list.