How to Create a New Custom Skill Using the Nx Generator in Agent-Skills

The @tech-leads-club/skill-plugin:skill Nx generator scaffolds a complete skill package in the packages/skills-catalog/skills/ directory by normalizing names, creating category folders, and templating the required SKILL.md file.

The tech-leads-club/agent-skills repository provides a dedicated Nx generator to streamline the creation of custom skills for the Agent-Skills catalog. When you create a new custom skill using the Nx generator, it handles directory structure, naming conventions, and boilerplate generation automatically, ensuring your skill integrates seamlessly with the CLI and Marketplace UI.

Running the Nx Skill Generator

Invoke the generator from the repository root using the Nx CLI. The generator supports both minimal and comprehensive configurations depending on your metadata requirements.

# Minimal invocation – creates an uncategorised skill

nx g @tech-leads-club/skill-plugin:skill my-skill

# Recommended invocation with category and metadata

nx g @tech-leads-club/skill-plugin:skill my-skill \
  --category=development \
  --description="Generate boiler-plate code for a new Node library" \
  --author="github.com/yourname" \
  --skillVersion="1.0.0"

The category flag determines whether the skill lands in a top-level folder or within a categorized sub-folder using the categoryIdToFolderName helper convention.

What the Generator Scaffolds

The generator implementation in tools/skill-plugin/src/generators/skill/skill.ts executes a precise six-step workflow to ensure consistency across all skills.

Name Normalization and Directory Structure

First, the generator calls Nx's names() utility to normalize your skill name, producing derived identifiers like fileName and className for internal use. It then calculates the target directory:

• Without category: packages/skills-catalog/skills/my-skill/
• With category: packages/skills-catalog/skills/(development)/my-skill/

The categoryIdToFolderName function wraps the category in parentheses, creating the (development), (testing), or (devops) folder structure used throughout the catalog.

Duplication Checks and File Generation

Before writing files, the generator verifies that SKILL.md does not already exist at the calculated path. If it detects a duplicate, the process aborts immediately to prevent overwrites.

Once cleared, generateFiles() copies everything from tools/skill-plugin/src/generators/skill/files/ into the new directory. Currently, this includes SKILL.md.template, which becomes the skill's primary definition file.

Template Interpolation and Formatting

The template engine interpolates variables using the normalized names and your CLI inputs:

• description – Populates the metadata front-matter
• author – Attribution for the skill registry
• skillVersion – Semantic version tracking
• name – The normalized skill identifier

After generation, await formatFiles(tree) runs Prettier across the new files to enforce code style consistency. The generator logs confirmation messages indicating whether it created a new category folder and the exact path to your SKILL.md.

The Generated Skill Structure

Each generated skill follows a standardized layout within the skills-catalog package:

packages/skills-catalog/skills/
└── (development)/                    # Optional category folder

    └── my-skill/
        ├── SKILL.md                  # Generated from template

        └── (optional) scripts/       # For complex skills requiring logic

The SKILL.md file contains required YAML front-matter and a skeleton markdown body:

---
name: my-skill
description: Generate boiler-plate code for a new Node library
metadata:
  version: 1.0.0
  author: github.com/yourname
---

# MySkill

Expert in TODO: describe expertise.

## Process

1. TODO: Step 1
2. TODO: Step 2
3. TODO: Step 3

## Examples

TODO: Add concrete input → output examples.

Testing Your New Skill

Validate your skill immediately using the Agent-Skills CLI without waiting for registry updates:

npx @tech-leads-club/agent-skills --skill my-skill

This command loads your skill directly from the file system, allowing you to verify the SKILL.md structure and content before committing changes.

How Skills Enter the Registry

Once your skill exists in packages/skills-catalog/skills/, the generate-registry script processes it. Located at packages/skills-catalog/src/generate-registry.ts, this utility scans the skills directory, parses each SKILL.md front-matter, and compiles skills-registry.json. This registry drives both the CLI skill discovery and the Marketplace web interface, ensuring your custom skill appears in the catalog after the next build.

Summary

• Use nx g @tech-leads-club/skill-plugin:skill to scaffold skills with proper naming conventions and folder structure.
• Specify --category to organize skills into (category) sub-folders via the categoryIdToFolderName helper.
• The generator prevents overwrites by checking for existing SKILL.md files before execution.
• Template variables (description, author, skillVersion) populate the front-matter of your generated SKILL.md.
• Test locally with npx @tech-leads-club/agent-skills --skill <name> before submitting.
• The registry updates automatically via generate-registry.ts when skills are added to the catalog.

Frequently Asked Questions

What happens if I try to create a skill that already exists?

The generator aborts with an error. In tools/skill-plugin/src/generators/skill/skill.ts, the code explicitly checks for the existence of SKILL.md at the calculated target path and stops execution to prevent accidental overwrites of existing skills.

Can I create a skill without a category?

Yes. Omitting the --category flag places the skill directly in packages/skills-catalog/skills/<skill-name>/. The generator treats uncategorised skills as top-level entries in the catalog structure.

How do I update the skill registry after creating a new skill?

Run the generate-registry script or simply build the project. The packages/skills-catalog/src/generate-registry.ts script automatically scans the skills directory and regenerates skills-registry.json to include your new skill in the CLI and Marketplace listings.

Where is the template for the SKILL.md file located?

The template resides at tools/skill-plugin/src/generators/skill/files/SKILL.md.template. The generator copies this file to your new skill directory and interpolates variables like name, description, and author into the front-matter and body content.

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