Creating Skills for magenta.nvim

This guide explains how to create custom skills that extend Claude's capabilities in magenta.nvim.

Skill Locations

Skills can be placed in several locations:

Global Skills

• Location: ~/.magenta/skills/ or ~/.claude/skills/
• Usage: Available across all projects
• Use case: General-purpose skills you want in every project
• Note: Both locations work identically; choose based on preference

Project-Specific Skills

• Location: .magenta/skills/ (in your project root)
• Usage: Only available in that specific project
• Use case: Project-specific workflows, conventions, or documentation

Skill Structure

Each skill lives in its own subdirectory with a skill.md file:

~/.magenta/skills/
└── your-skill-name/
    ├── skill.md          # Required: main skill documentation
    └── scripts/          # Optional: executable scripts
        └── helper.ts     # Optional: TypeScript scripts

skill.md Format

The skill.md file must include YAML frontmatter with required fields:

---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---

# Your Skill Documentation

Write your skill documentation here in markdown format.

This can include:

- Detailed explanations
- Code examples
- Best practices
- Step-by-step instructions
- References to other files or resources

Required Frontmatter Fields

• name: Unique identifier for the skill (lowercase with hyphens recommended)
• description: Short description that gives the agent some hints as to the content of the full skill.md file.

TypeScript Scripts in Skills

Skills can include executable TypeScript scripts using pkgx for zero-setup execution.

What is pkgx?

pkgx is a package runner that automatically installs and runs packages on-demand without needing a full npm project setup. It's perfect for skill scripts since it eliminates boilerplate.

Creating a Script

1. Create a scripts/ directory in your skill folder
2. Add a .ts file with a pkgx shebang:

#!/usr/bin/env -S pkgx +typescript +npx tsx

// Your TypeScript code here
console.log("Hello from a skill script!");

// You can use TypeScript features directly
interface Config {
  name: string;
  value: number;
}

const config: Config = {
  name: "example",
  value: 42,
};

console.log(config);

3. Make it executable and run:

chmod +x ~/.magenta/skills/your-skill-name/scripts/your-script.ts
./scripts/your-script.ts

Or run directly with pkgx:

pkgx +typescript npx tsx scripts/your-script.ts

Running Shell Commands with zx

For scripts that need to run shell commands, use Google's zx library:

#!/usr/bin/env -S pkgx +typescript +npx +zx tsx

import { $ } from "zx";

const result = await $`ls -la`;
console.log(result.stdout);

Script Requirements

• pkgx: Install from https://pkgx.sh (curl -Ssf https://pkgx.sh | sh)
• No npm setup required - pkgx handles all dependencies automatically