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

Run npm run generate:skill-stubs with the --name, --description, and --profiles flags to scaffold a new skill directory complete with skill.json, 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:

npm install

This installs the workspace dependencies required by the scaffolding script located at 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:

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

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 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 to populate the skills index.

Example structure:

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

instruction.md

The instruction.md file serves as the human-readable instruction document. During runtime, the assembler in packages/k-skill-cli/src/assemble.js merges this file with profile-specific templates (such as core.md or 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:

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:

npx k-skill instruct my-awesome-skill

This command invokes the assembler logic from packages/k-skill-cli/src/assemble.js, which processes your skill.json and instruction.md along with the profile templates specified during generation.

Executing Helper Scripts

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

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, 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 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, lookup.md, and action-booking.md) into the new skill directory.
3. Writes configuration – generates skill.json and 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, 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, lookup.md, and 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 entry point reads the skill.json files from all subdirectories in packages/k-skill-cli/skills/ to build the available commands list.

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