{"id":34724587,"url":"https://github.com/tubone24/midi-agent-skill","last_synced_at":"2026-05-23T18:34:22.870Z","repository":{"id":329549094,"uuid":"1119839941","full_name":"tubone24/midi-agent-skill","owner":"tubone24","description":"MIDI Agent Skill is Agent Skills that enables AI models to generate MIDI files from text-based music data. This tool allows for programmatic creation of musical compositions through a standardized interface.","archived":false,"fork":false,"pushed_at":"2025-12-25T00:28:30.000Z","size":50,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T13:31:02.296Z","etag":null,"topics":["agent-skills","midi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tubone24.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-20T00:13:49.000Z","updated_at":"2025-12-21T02:08:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tubone24/midi-agent-skill","commit_stats":null,"previous_names":["tubone24/midi-agent-skill"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tubone24/midi-agent-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubone24%2Fmidi-agent-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubone24%2Fmidi-agent-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubone24%2Fmidi-agent-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubone24%2Fmidi-agent-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tubone24","download_url":"https://codeload.github.com/tubone24/midi-agent-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubone24%2Fmidi-agent-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","midi"],"created_at":"2025-12-25T02:19:59.943Z","updated_at":"2026-05-23T18:34:22.863Z","avatar_url":"https://github.com/tubone24.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MIDI Generation Skill\n\n**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**.\n\n---\n\n## Features\n\n- Generate MIDI from text prompts\n- 128 GM instruments - Full General MIDI support (A320U.sf2 compatible)\n- WAV export - Convert MIDI to audio using FluidSynth\n- Claude Skills compatible - Automatic skill invocation\n- Python implementation using midiutil\n\n---\n\n## Repository Structure\n\n```\n/\n├─ skills/                   # Skill implementation (Python)\n│   ├─ generate_midi.py          # MIDI file generation\n│   ├─ convert_to_wav.py         # MIDI to WAV conversion (FluidSynth)\n│   ├─ normalize_composition.py  # Input validation\n│   └─ refine_composition.py     # Adjust composition length\n├─ midi_types/\n│   ├─ music.py                  # Composition types\n│   └─ gm_instruments.py         # 128 GM instruments list\n├─ resources/                # Music theory references\n│   ├─ music-theory.md\n│   ├─ chord-progressions.md\n│   ├─ voice-leading.md\n│   ├─ counterpoint.md\n│   ├─ modes-scales.md\n│   ├─ rhythm-patterns.md\n│   └─ orchestration.md\n├─ soundfonts/               # Place A320U.sf2 here\n├─ output/                   # Generated MIDI/WAV files\n├─ SKILL.md                  # Claude Skill definition\n├─ requirements.txt          # Python dependencies\n└─ README.md\n```\n\n---\n\n## Supported Instruments\n\nAll 128 General MIDI instruments are supported. Common examples:\n\n| Category | Instruments |\n|----------|-------------|\n| Piano | `acoustic-grand-piano`, `electric-piano-1`, `harpsichord` |\n| Guitar | `acoustic-guitar-nylon`, `electric-guitar-clean`, `distortion-guitar` |\n| Bass | `acoustic-bass`, `electric-bass-finger`, `synth-bass-1` |\n| Strings | `violin`, `cello`, `string-ensemble-1`, `orchestral-harp` |\n| Brass | `trumpet`, `trombone`, `french-horn`, `brass-section` |\n| Woodwind | `flute`, `clarinet`, `oboe`, `alto-sax` |\n| Synth | `lead-1-square`, `pad-1-new-age`, `synth-strings-1` |\n\nSimple aliases like `piano`, `guitar`, `bass`, `strings`, `brass`, `sax` are also supported.\n\nSee `midi_types/gm_instruments.py` for the full list.\n\n---\n\n## Installation\n\n### 1. Install Python dependencies\n\n```bash\npip install midiutil\n```\n\nOr using requirements.txt:\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. Download SoundFont (for WAV conversion)\n\n1. Download **A320U.sf2** from [Musical Artifacts](https://musical-artifacts.com/artifacts/5906)\n2. Place it in `soundfonts/A320U.sf2`\n\n### 3. Install FluidSynth (for WAV conversion)\n\n```bash\n# macOS\nbrew install fluidsynth\n\n# Linux\napt-get install fluidsynth\n```\n\n---\n\n## Usage with Claude.ai\n\n### 1. Enable Skills in Claude\n\n1. Open **Claude Settings**\n2. Enable **Skills**\n3. Upload this repository as a **ZIP file**\n4. Turn the skill **ON**\n\n### 2. Use the Skill\n\nSimply ask Claude something related to music:\n\n```text\nAdded 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.\n```\n\nClaude will automatically:\n1. Detect that the request matches this skill\n2. Use the provided Python scripts in `skills/` directory\n3. Generate MIDI with proper GM instruments (each track on different channel)\n4. Optionally convert to WAV\n\n### Demo\n\n\n\nhttps://github.com/user-attachments/assets/34f018e5-6354-40a9-9426-15d2ccc7c39a\n\n\n\n---\n\n## Composition Format\n\nThe skill uses a structured JSON format:\n\n```json\n{\n  \"title\": \"My Song\",\n  \"bpm\": 120,\n  \"tracks\": [\n    {\n      \"instrument\": \"acoustic-grand-piano\",\n      \"notes\": [\n        { \"pitch\": \"C4\", \"duration\": \"4\" },\n        { \"pitch\": \"E4\", \"duration\": \"4\" },\n        { \"pitch\": \"G4\", \"duration\": \"2\" }\n      ]\n    },\n    {\n      \"instrument\": \"acoustic-bass\",\n      \"notes\": [\n        { \"pitch\": \"C2\", \"duration\": \"1\" }\n      ]\n    }\n  ]\n}\n```\n\n### Note Duration Values\n\n| Value | Duration |\n|-------|----------|\n| `\"1\"` | Whole note (4 beats) |\n| `\"2\"` | Half note (2 beats) |\n| `\"d2\"` | Dotted half (3 beats) |\n| `\"4\"` | Quarter note (1 beat) |\n| `\"d4\"` | Dotted quarter (1.5 beats) |\n| `\"8\"` | Eighth note (0.5 beats) |\n| `\"16\"` | Sixteenth note (0.25 beats) |\n\n---\n\n## API Reference\n\n### `generate_midi(composition: Composition) -\u003e str`\n\nGenerate a MIDI file from a Composition object.\n\n- **Input**: Composition object with title, bpm, and tracks\n- **Output**: Path to the generated `.mid` file\n\n### `generate_midi_from_dict(data: dict) -\u003e str`\n\nGenerate a MIDI file from a dictionary.\n\n- **Input**: Dictionary with title, bpm, and tracks\n- **Output**: Path to the generated `.mid` file\n\n### `convert_to_wav(midi_path: str, options: ConvertOptions) -\u003e str`\n\nConvert a MIDI file to WAV using FluidSynth and A320U.sf2.\n\n- **Input**: Path to MIDI file\n- **Output**: Path to the generated `.wav` file\n\n### `normalize_composition(data: Any) -\u003e Composition`\n\nValidate and normalize user input into a proper Composition object.\n\n### `refine_composition(composition: Composition, min_notes: int) -\u003e Composition`\n\nAdjust composition length (ensures minimum notes per track).\n\n### `resolve_instrument(name: str) -\u003e int`\n\nConvert instrument name to GM program number (0-127).\n\n---\n\n## Example Prompts\n\n```text\nCreate a calm ambient piece with pad synths and strings\n```\n\n```text\nGenerate a rock song with distortion guitar and drums at 140 BPM\n```\n\n```text\nCompose a classical piece with violin, cello, and harpsichord\n```\n\n---\n\n## Development Notes\n\n- `SKILL.md` defines **when and how Claude should use this skill**\n- The `skills/` directory contains **pre-built Python scripts that Claude must use**\n- Claude should **NOT write custom code** - it should use the provided functions\n- All instruments are GM-compatible for A320U.sf2 playback\n- **Each track is assigned to a different MIDI channel** for proper multi-instrument playback\n\n---\n\n## License\n\nMIT License\n\nSee LICENSE.txt for details including third-party licenses.\n\n---\n\n## References\n\n- [A320U SoundFont](https://musical-artifacts.com/artifacts/5906)\n- [General MIDI Specification](https://www.midi.org/specifications/midi1-specifications/general-midi-specifications)\n- [Claude Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)\n- [FluidSynth](https://www.fluidsynth.org/)\n- [MIDIUtil](https://github.com/MarkCWirt/MIDIUtil)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftubone24%2Fmidi-agent-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftubone24%2Fmidi-agent-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftubone24%2Fmidi-agent-skill/lists"}