# How to Create a New Custom Skill Using the Nx Generator in Agent-Skills > Learn to create a new custom skill using the Nx generator in Agent-Skills. This tool scaffolds a complete skill package, simplifying development. - Repository: [TechLeads.club 💎/agent-skills](https://github.com/tech-leads-club/agent-skills) - Tags: how-to-guide - Published: 2026-05-18 --- **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`](https://github.com/tech-leads-club/agent-skills/blob/main/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. ```bash # 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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) file contains required YAML front-matter and a skeleton markdown body: ```markdown --- 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: ```bash 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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/src/generate-registry.ts), this utility scans the skills directory, parses each [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) front-matter, and compiles [`skills-registry.json`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) files before execution. - **Template variables** (`description`, `author`, `skillVersion`) populate the front-matter of your generated [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md). - **Test locally** with `npx @tech-leads-club/agent-skills --skill ` before submitting. - **The registry updates** automatically via [`generate-registry.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/tools/skill-plugin/src/generators/skill/skill.ts), the code explicitly checks for the existence of [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/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//`. 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`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/src/generate-registry.ts) script automatically scans the skills directory and regenerates [`skills-registry.json`](https://github.com/tech-leads-club/agent-skills/blob/main/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.