Locofy Docs
CLISkillsCreating Custom Skills

Creating Custom Skills

Define project-specific skills for Locofy CLI with SKILL.md files.

Custom skills let you encode team standards, migration patterns, and framework choices so the Locofy CLI agent applies them consistently—for example, migrating CSS Modules to Bootstrap, enforcing a specific form library, or matching an internal component library.

When to create a custom skill

Create a custom skill when your team repeatedly gives the same instructions in Interactive Mode:

  • "Convert CSS Modules to Bootstrap utility classes"
  • "Always use our Button from @/components/ui"
  • "Use react-hook-form with Zod for all forms"
  • "Place feature code under src/features/<name>/"

If the instruction spans multiple steps or needs reference files, a skill is more reliable than a one-off prompt.

Skill directory structure

Each skill is a folder containing a SKILL.md file. Optional supporting files go in subdirectories (commonly references/):

.locofy/locofy/skills/
└── css-modules-to-bootstrap/
    ├── SKILL.md
    └── references/
        └── class-mapping.md

Where to place skills

LocationScope
.locofy/locofy/skills/<skill-name>/Project (recommended; commit to version control)
locofy/skills/<skill-name>/Project (legacy path)
~/.locofy/skills/<skill-name>/User-level (all projects on your machine)

Project skills in .locofy/locofy/skills/ take priority over user-level skills in ~/.locofy/skills/.

SKILL.md format

Every skill must start with YAML frontmatter, followed by markdown instructions:

---
name: my-skill-name
description: Short summary shown in the agent's skill list
frameworks:
  - react
  - next
allowed-tools:
  - read
  - edit
  - glob
metadata:
  version: '1.0'
  author: 'your-team'
---

# My Skill Title

Instructions the agent follows when this skill is loaded...

Frontmatter fields

FieldRequiredDescription
nameYesSkill identifier—must match the folder name
descriptionYesOne-line summary listed at session start
frameworksNoLimit visibility to specific frameworks (e.g. react, next, vue)
allowed-toolsNoRestrict which agent tools the skill may use
metadataNoArbitrary key-value metadata (version, author, etc.)

The agent loads the full SKILL.md when you invoke the skill in Interactive Mode.

Example: CSS Modules to Bootstrap

This skill migrates components that use CSS Modules to Bootstrap 5 utility classes—useful when Locofy generates .module.css files but your project standard is Bootstrap.

1. Create the skill folder

mkdir -p .locofy/locofy/skills/css-modules-to-bootstrap/references

2. Write SKILL.md

---
name: css-modules-to-bootstrap
description: Convert CSS Modules styling to Bootstrap 5 utility classes and components
frameworks:
  - react
  - next
allowed-tools:
  - read
  - edit
  - glob
  - grep
metadata:
  version: '1.0'
  author: 'your-team'
---

# CSS Modules to Bootstrap

Migrate React components from CSS Modules to Bootstrap 5. Run when generated or merged code uses `import styles from './X.module.css'` but the project uses Bootstrap.

## Prerequisites

- Bootstrap 5 CSS is already imported in the app entry (e.g. `import 'bootstrap/dist/css/bootstrap.min.css'`)
- Do not add new CSS files unless a style has no Bootstrap equivalent

## Migration steps

1. **Read the component and its `.module.css` file** before editing.
2. **Remove the CSS Module import** (`import styles from './Component.module.css'`).
3. **Replace `className={styles.foo}`** with Bootstrap `className` strings. Combine utilities with template literals or `clsx` if the project already uses it.
4. **Delete the `.module.css` file** once all classes are migrated.
5. **Use Bootstrap components** where appropriate:
   - Buttons → `btn btn-primary`, `btn btn-outline-secondary`
   - Forms → `form-control`, `form-label`, `form-check`
   - Layout → `container`, `row`, `col-*`, `d-flex`, `gap-*`
   - Spacing → `m-*`, `p-*`, `mt-*`, `mb-*`, `px-*`, `py-*`
6. **Preserve behaviour** — event handlers, conditional classes, and responsive breakpoints must work the same after migration.
7. **Verify** the file compiles and imports resolve.

## Class mapping reference

Read `references/class-mapping.md` for common Locofy CSS Module patterns and their Bootstrap equivalents.

## Rules

- Prefer utility classes over custom CSS
- Use `d-none d-md-block` (and similar) for responsive show/hide
- Map flex layouts to `d-flex`, `flex-column`, `justify-content-*`, `align-items-*`
- Map fixed widths to responsive grid: `col-12 col-md-6 col-lg-4`
- Keep semantic HTML — do not wrap everything in extra `div`s just to apply flex utilities
- If a style has no Bootstrap equivalent, add a single scoped class in an existing global stylesheet only as a last resort

3. Add a reference file (optional)

Create references/class-mapping.md:

# CSS Module → Bootstrap mapping

| CSS Module pattern | Bootstrap equivalent |
| ------------------ | -------------------- |
| `display: flex` | `d-flex` |
| `flex-direction: column` | `flex-column` |
| `justify-content: center` | `justify-content-center` |
| `align-items: center` | `align-items-center` |
| `gap: 16px` | `gap-3` |
| `padding: 24px` | `p-4` |
| `margin-bottom: 16px` | `mb-3` |
| `width: 100%` | `w-100` |
| `border-radius: 8px` | `rounded` |
| `font-weight: 600` | `fw-semibold` |
| `box-shadow: ...` | `shadow-sm` or `shadow` |
| Primary button styles | `btn btn-primary` |
| Text input styles | `form-control` |

4. Invoke in Interactive Mode

After locofy convert or locofy pull:

Load the css-modules-to-bootstrap skill and convert HeroSection.tsx and its module CSS to Bootstrap
Use css-modules-to-bootstrap on all files in components/landing/ — keep btn-lg on primary CTAs

5. Iterate

Review the diff in your IDE. Refine SKILL.md with project-specific rules (your button variants, grid breakpoints, or clsx patterns) until output is consistent.

Tips for effective custom skills

  • Be specific — include import paths, class names, and concrete before/after examples.
  • One concern per skill — separate styling migrations from form validation or folder structure rules.
  • Use references/ for long mapping tables, probe scripts, or example files the agent should read.
  • Set frameworks when a skill only applies to one stack—keeps the skill list relevant.
  • Commit project skills — store them under .locofy/locofy/skills/ so the whole team shares the same instructions.

What's next

Using Skills

Figma Components

On this page

When to create a custom skillSkill directory structureWhere to place skillsSKILL.md formatFrontmatter fieldsExample: CSS Modules to Bootstrap1. Create the skill folder2. Write SKILL.md3. Add a reference file (optional)4. Invoke in Interactive Mode5. IterateTips for effective custom skillsWhat's next