MIDI Generation Skill

MIDI Generation Skill is a custom Agent Skill for Claude.ai that enables AI agents to generate MIDI files from natural language music descriptions, with full General MIDI instrument support optimized for the A320U.sf2 SoundFont.

---

Features

• Generate MIDI from text prompts
• 128 GM instruments - Full General MIDI support (A320U.sf2 compatible)
• WAV export - Convert MIDI to audio using FluidSynth
• Claude Skills compatible - Automatic skill invocation
• Python implementation using midiutil

---

Repository Structure

/
├─ skills/                   # Skill implementation (Python)
│   ├─ generate_midi.py          # MIDI file generation
│   ├─ convert_to_wav.py         # MIDI to WAV conversion (FluidSynth)
│   ├─ normalize_composition.py  # Input validation
│   └─ refine_composition.py     # Adjust composition length
├─ midi_types/
│   ├─ music.py                  # Composition types
│   └─ gm_instruments.py         # 128 GM instruments list
├─ resources/                # Music theory references
│   ├─ music-theory.md
│   ├─ chord-progressions.md
│   ├─ voice-leading.md
│   ├─ counterpoint.md
│   ├─ modes-scales.md
│   ├─ rhythm-patterns.md
│   └─ orchestration.md
├─ soundfonts/               # Place A320U.sf2 here
├─ output/                   # Generated MIDI/WAV files
├─ SKILL.md                  # Claude Skill definition
├─ requirements.txt          # Python dependencies
└─ README.md

---

Supported Instruments

All 128 General MIDI instruments are supported. Common examples:

Category	Instruments
Piano	acoustic-grand-piano, electric-piano-1, harpsichord
Guitar	acoustic-guitar-nylon, electric-guitar-clean, distortion-guitar
Bass	acoustic-bass, electric-bass-finger, synth-bass-1
Strings	violin, cello, string-ensemble-1, orchestral-harp
Brass	trumpet, trombone, french-horn, brass-section
Woodwind	flute, clarinet, oboe, alto-sax
Synth	lead-1-square, pad-1-new-age, synth-strings-1

Simple aliases like piano, guitar, bass, strings, brass, sax are also supported.

See midi_types/gm_instruments.py for the full list.

---

Installation

1. Install Python dependencies

pip install midiutil

Or using requirements.txt:

pip install -r requirements.txt

2. Download SoundFont (for WAV conversion)

1. Download A320U.sf2 from Musical Artifacts
2. Place it in soundfonts/A320U.sf2

3. Install FluidSynth (for WAV conversion)

# macOS
brew install fluidsynth

# Linux
apt-get install fluidsynth

---

Usage with Claude.ai

1. Enable Skills in Claude

1. Open Claude Settings
2. Enable Skills
3. Upload this repository as a ZIP file
4. Turn the skill ON

2. Use the Skill

Simply ask Claude something related to music:

Added the “midi-generation” skill. Use it to create grand classical music. I look forward to bright, grand, and beautiful melodies layered together. Once you have the MIDI, please convert it to WAV.

Claude will automatically:

1. Detect that the request matches this skill
2. Use the provided Python scripts in skills/ directory
3. Generate MIDI with proper GM instruments (each track on different channel)
4. Optionally convert to WAV

Demo

https://github.com/user-attachments/assets/34f018e5-6354-40a9-9426-15d2ccc7c39a

---

Composition Format

The skill uses a structured JSON format:

{
  "title": "My Song",
  "bpm": 120,
  "tracks": [
    {
      "instrument": "acoustic-grand-piano",
      "notes": [
        { "pitch": "C4", "duration": "4" },
        { "pitch": "E4", "duration": "4" },
        { "pitch": "G4", "duration": "2" }
      ]
    },
    {
      "instrument": "acoustic-bass",
      "notes": [
        { "pitch": "C2", "duration": "1" }
      ]
    }
  ]
}

Note Duration Values

Value	Duration
"1"	Whole note (4 beats)
"2"	Half note (2 beats)
"d2"	Dotted half (3 beats)
"4"	Quarter note (1 beat)
"d4"	Dotted quarter (1.5 beats)
"8"	Eighth note (0.5 beats)
"16"	Sixteenth note (0.25 beats)

---

API Reference

generate_midi(composition: Composition) -> str

Generate a MIDI file from a Composition object.

• Input: Composition object with title, bpm, and tracks
• Output: Path to the generated .mid file

generate_midi_from_dict(data: dict) -> str

Generate a MIDI file from a dictionary.

• Input: Dictionary with title, bpm, and tracks
• Output: Path to the generated .mid file

convert_to_wav(midi_path: str, options: ConvertOptions) -> str

Convert a MIDI file to WAV using FluidSynth and A320U.sf2.

• Input: Path to MIDI file
• Output: Path to the generated .wav file

normalize_composition(data: Any) -> Composition

Validate and normalize user input into a proper Composition object.

refine_composition(composition: Composition, min_notes: int) -> Composition

Adjust composition length (ensures minimum notes per track).

resolve_instrument(name: str) -> int

Convert instrument name to GM program number (0-127).

---

Example Prompts

Create a calm ambient piece with pad synths and strings

Generate a rock song with distortion guitar and drums at 140 BPM

Compose a classical piece with violin, cello, and harpsichord

---

Development Notes

• SKILL.md defines when and how Claude should use this skill
• The skills/ directory contains pre-built Python scripts that Claude must use
• Claude should NOT write custom code - it should use the provided functions
• All instruments are GM-compatible for A320U.sf2 playback
• Each track is assigned to a different MIDI channel for proper multi-instrument playback

---

License

MIT License

See LICENSE.txt for details including third-party licenses.

---

References

• A320U SoundFont
• General MIDI Specification
• Claude Agent Skills
• FluidSynth
• MIDIUtil