max-resources - SKILL.md Agent Skill

name: max-resources description: | Access Max/MSP built-in resources. Use when: - User asks about Max objects ("How do I use cycle~?") - User wants to find examples or snippets - User needs object reference information (inlets, outlets, methods) argument-hint: "[|fts ]"

Max Resources Skill

Access Max/MSP built-in resources directly from Max.app: reference pages, snippets, example patches, and user guides.

Agentic Search Approach

This skill uses direct filesystem exploration with Claude Code's built-in tools. No pre-built indexes required - information is always current.

Use Claude Code's dedicated tools instead of Bash commands:

Purpose	Use This Tool	Not This
Find files by pattern	Glob	~~find~~
Search file contents	Grep	~~grep~~
Read file contents	Read	~~cat~~

Resource Locations

All resources are located within Max.app:

/Applications/Max.app/Contents/Resources/
+-- C74/docs/refpages/           # Object references (XML)
|   +-- max-ref/                 # Max objects (~473)
|   +-- msp-ref/                 # MSP/audio objects (~455)
|   +-- jit-ref/                 # Jitter/video objects (~210)
|   \-- m4l-ref/                 # Max for Live (~37)
+-- C74/docs/userguide/          # User guides
|   \-- content/                 # Guide content (JSON, full-text searchable)
+-- C74/snippets/                # Code snippets (.maxsnip)
|   +-- max/
|   +-- msp/
|   \-- jitter/
\-- Examples/                    # Example patches (.maxpat)
    +-- effects/
    +-- synths/
    +-- sequencing-looping/
    \-- jitter-examples/

Search Methods Using Claude Code Tools

1. Object Reference Lookup

When user asks about a specific object (e.g., "How do I use cycle~?"):

# Use Glob to find the reference file
Glob: pattern="**/cycle~.maxref.xml"
      path="/Applications/Max.app/Contents/Resources/C74/docs/refpages"

# Use Read to get the content
Read: file_path="/Applications/Max.app/.../msp-ref/cycle~.maxref.xml"

Reference file naming: {object-name}.maxref.xml

Objects with ~ suffix: audio/signal objects (MSP)
Objects without ~: control/message objects (Max)

2. Object Search (Pattern Matching)

When user searches for objects by keyword:

# Find objects matching a pattern
Glob: pattern="**/*filter*.maxref.xml"
      path="/Applications/Max.app/Contents/Resources/C74/docs/refpages"

# Search within XML content
Grep: pattern="frequency"
      path="/Applications/Max.app/Contents/Resources/C74/docs/refpages"
      glob="*.maxref.xml"

3. Full-Text Documentation Search

To search the user guide text, Grep over the guide content JSON:

Grep: pattern="oscillator"
      path="/Applications/Max.app/Contents/Resources/C74/docs/userguide/content"
      glob="*.json"
      output_mode="files_with_matches"

This searches the same user-guide source text directly - no database or index required, and results always match the installed Max version.

4. Example Patches

# List example categories
Glob: pattern="*"
      path="/Applications/Max.app/Contents/Resources/Examples"

# Find examples containing specific objects
Grep: pattern="cycle~"
      path="/Applications/Max.app/Contents/Resources/Examples"
      glob="*.maxpat"

5. Snippets

# List snippet categories
Glob: pattern="*"
      path="/Applications/Max.app/Contents/Resources/C74/snippets"

# Find snippets
Glob: pattern="**/*.maxsnip"
      path="/Applications/Max.app/Contents/Resources/C74/snippets"

XML Reference Format

Reference files use .maxref.xml format. Key elements to extract:

<c74object name="cycle~" module="msp" category="MSP Synthesis">
    <digest>Sinusoidal oscillator</digest>
    <description>Full description...</description>

    <inletlist>
        <inlet id="0" type="signal/float">
            <digest>Frequency (Hz)</digest>
        </inlet>
    </inletlist>

    <outletlist>
        <outlet id="0" type="signal">
            <digest>Output signal</digest>
        </outlet>
    </outletlist>

    <objarglist>
        <objarg name="frequency" optional="1" type="number">
            <digest>Initial frequency</digest>
        </objarg>
    </objarglist>

    <methodlist>
        <method name="float">...</method>
    </methodlist>

    <attributelist>
        <attribute name="interp" type="int">...</attribute>
    </attributelist>

    <seealsolist>
        <seealso name="phasor~"/>
    </seealsolist>
</c74object>

Key XML Elements to Extract

Element	Content	Use For
`<digest>`	One-line summary	Quick overview
`<description>`	Full description	Detailed explanation
`<inletlist>/<inlet>`	Input specs	Understanding inputs
`<outletlist>/<outlet>`	Output specs	Understanding outputs
`<objarglist>/<objarg>`	Creation arguments	Object instantiation
`<methodlist>/<method>`	Available methods	Messages the object accepts
`<attributelist>/<attribute>`	Object attributes	Configurable properties
`<seealsolist>/<seealso>`	Related objects	Finding alternatives

Helper Scripts (Optional)

Lightweight helper scripts for operations that require Bash:

Script	Purpose	When to Use
`get-reference.sh`	Get object reference	Convenient summary extraction
`list-examples.sh`	List example patches	Browse examples
`get-snippet.sh`	Get code snippets	Browse snippets

Note: Prefer using Glob/Grep/Read tools directly. The scripts are thin convenience wrappers around the same filesystem lookups.

When to Use

必須参照（推測で接続しない）

以下の場合、推測せずにこのスキルでリファレンスを確認する:

outlet/inlet の役割が不明なオブジェクトに接続する前: outlet の数だけでなく、各 outlet が何を出力するかを確認（例: pattr は 3 outlet だが、outlet 1 は bindto 専用）
オブジェクトに送るメッセージの形式が不明な時: live.object の set value N vs value N のように、メッセージ形式が正しくないと動作しない
アトリビュート値の意味が不明な時: live.dial の appearance (0=Vertical, 1=Tiny, 2=Panel, 3=Large) のように、値の意味をリファレンスで確認

推測による接続・設定は手戻りの最大の原因。1回のリファレンス確認で防げる問題を、推測→失敗→修正のサイクルで3回以上のやり取りに増やさない。

ユーザーからの質問

Use this skill when users ask about:

Max object usage ("How do I use cycle~?")
Object parameters, inlets, outlets, methods
Example patches ("Show me FM synthesis examples")
Snippets and code patterns
Max concepts and tutorials

Trigger words: "Max object", "reference", "how to use", "example", "snippet", "documentation", "inlet", "outlet", "method"

Workflow Examples

Example 1: Object Lookup

User: "How do I use metro?"

Glob to find: **/metro.maxref.xml
Read the XML file
Extract digest, description, inlets, outlets
Present formatted information

Example 2: Search for Objects

User: "What filter objects are available?"

Glob to search: **/*filter*.maxref.xml
List matching objects
Read top results to extract digests
Present categorized list

Example 3: Find Examples

User: "Show me reverb examples"

Grep in Examples directory for "reverb"
Or Glob for **/*reverb*.maxpat
List matching patches with paths

Max.app Path Detection

If Max.app is not at the default location, use Bash to detect:

mdfind "kMDItemCFBundleIdentifier == 'com.cycling74.Max'" | head -1

Detailed Documentation

For format specifications:

references/resource-paths.md - Full path reference
references/refpage-format.md - XML format details
references/maxpat-format.md - Patch JSON format
references/mcp-recreation.md - Example-to-patch workflow
examples/lookup-object.md - Lookup examples
examples/recreate-patch.md - Patch recreation examples