How to Create a New Skill Using Impeccable's Unified Skills Architecture

Create a new skill in Impeccable by adding a directory under source/skills/ containing a SKILL.md file with YAML front-matter, then run bun run build to generate provider-specific bundles for Cursor, Claude Code, Gemini, and others.

Impeccable (pbakaus/impeccable) is an open-source framework that manages AI assistant capabilities through a unified skills architecture. Instead of maintaining separate definitions for each IDE or AI coding tool, you define every skill once in a canonical source tree, and the build system automatically transforms these into the native formats required by each provider.

Understanding the Unified Skills Architecture

Impeccable stores every skill in one canonical source tree located at source/skills/. During the build process, the readSourceFiles function in scripts/lib/utils.js recursively scans this directory, parsing each SKILL.md file to extract metadata from YAML front-matter and instruction text from the body. These unified skill objects are then passed to provider-specific transformers that generate the required file structures for Cursor, Claude Code, Gemini, Codex, and other supported platforms.

Because all providers derive from the same source objects, adding a skill automatically makes it available everywhere without provider-specific hand-editing.

Step-by-Step: Create a New Skill in Impeccable

1. Create the Skill Directory Structure

Create a new folder under source/skills/ named after your skill. This directory will contain the canonical definition that feeds all providers.

mkdir source/skills/your-skill-name

The build system expects this folder to contain at minimum a SKILL.md file. You may also add an optional reference/ subfolder for supporting documentation.

2. Write the SKILL.md File

Create SKILL.md inside your new directory with YAML front-matter followed by the instruction body. The front-matter fields are parsed by parseFrontmatter in scripts/lib/utils.js and drive how the skill appears across different AI tools.

---
name: highlight
description: Emphasize key UI elements with visual hierarchy
args:
  - name: selector
    description: CSS selector for the element(s) to highlight
    required: true
user-invokable: true
---
Identify the most important UI components on the page and apply a visual highlight to the elements matching \`{{selector}}\`.

Ensure the highlight respects the design system's color tokens and maintains accessibility contrast ratios.

Key front-matter fields include:

• name – The command identifier used when invoking the skill
• description – Brief explanation shown in command palettes
• args – Array of parameters with name, description, and required status
• user-invokable – Boolean determining if the skill appears in provider command palettes
• allowed-tools – Optional array restricting which tools the AI can use when executing this skill

3. Add Optional Reference Documentation

If your skill requires extensive guidelines, create a reference/ folder inside your skill directory. Any .md files placed here are loaded into the skill object's references array by the loop at lines 27-40 in scripts/lib/utils.js.

source/skills/highlight/
├── SKILL.md
└── reference/
    ├── contrast-guidelines.md
    └── accent-colors.md

The transformers can embed these references into provider-specific formats that support extended context, such as Cursor's .cursor/rules or Claude Code's system prompts.

4. Build and Distribute

Execute the build pipeline to generate provider-specific outputs:

# Install dependencies if needed

bun install

# Build all provider bundles

bun run build

The build() function in scripts/build.js (starting at line 64) orchestrates the pipeline: it calls readSourceFiles to load skills, runs each transformer, assembles universal bundles, and creates ZIP archives. Your new skill will appear in:

• dist/cursor/.cursor/skills/<skill-name>/SKILL.md
• dist/claude-code/.claude/skills/<skill-name>/SKILL.md
• dist/gemini/.gemini/skills/<skill-name>/...
• dist/codex/.codex/skills/<skill-name>/SKILL.md

Copy the generated folder into your project:

cp -r dist/cursor/.cursor your-project/

Because user-invokable is set to true, the command appears in your provider's command palette (e.g., type /highlight .hero-banner in Cursor).

How the Build System Processes Your Skill

The transformation pipeline relies on three core components in scripts/lib/utils.js:

readSourceFiles scans source/skills/ and expects each skill folder to contain a SKILL.md file. It validates the presence of required files and initiates parsing.

parseFrontmatter extracts the YAML metadata from the top of each SKILL.md file (lines 44-52 in utils.js). This function preserves keys like user-invokable, args, and allowed-tools unchanged for the transformers to consume.

Provider Transformers (scripts/lib/transformers/index.js) convert the unified skill objects into native formats. For example, transformCursor generates the specific JSON and markdown structures Cursor expects in its .cursor/ directory, while transformClaudeCode produces the appropriate .claude/ configuration.

Summary

• Create a directory under source/skills/<skill-name>/ to house your new skill
• Write a SKILL.md file with required YAML front-matter (name, description, args, user-invokable) and instruction body
• Optionally add supporting docs in a reference/ subfolder for extended context
• Run bun run build to execute the pipeline in scripts/build.js and generate provider bundles
• Distribute by copying the generated folders from dist/<provider>/ into your target projects

Frequently Asked Questions

What file naming conventions does Impeccable enforce for new skills?

Impeccable requires exactly one SKILL.md file per skill directory. The directory name becomes the skill identifier, and the name field in the front-matter should match this folder name. Reference files in the optional reference/ folder must use the .md extension, but otherwise can be named descriptively (e.g., api-reference.md, examples.md).

Can I make a skill available to only specific AI providers?

While the unified architecture generates outputs for all providers simultaneously, you can control visibility using front-matter flags. The user-invokable field determines if the skill appears in command palettes, though the skill definition still exists in the generated bundles. To completely exclude a skill from specific providers, you would need to modify the provider transformers in scripts/lib/transformers/ to filter based on custom metadata flags you add to the front-matter.

How do I test a skill before distributing it to my team?

After running bun run build, copy the specific provider folder from dist/ into a test project rather than your main repository. For Cursor, run cp -r dist/cursor/.cursor test-project/ and open that project in Cursor to verify the skill appears in the command palette and executes correctly. The build process is deterministic, so once verified, you can safely distribute the same dist/ artifacts to production environments.

What happens if the SKILL.md front-matter is malformed?

The parseFrontmatter function in scripts/lib/utils.js parses the YAML front-matter at the start of each SKILL.md file. If the YAML is malformed or required fields like name are missing, the build script will likely throw an error or produce undefined behavior in the transformers. Always validate your YAML syntax and ensure required keys (name, description) are present before running bun run build.

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