Meditation Music Composition

SKILL.md - meditation-music-composition

Skill Registration & Resolution

Skill Identity

• Name: meditation-music-composition
• Version: 1.1.0
• Domain: Music Therapy & Applied Psychoacoustics
• Type: Analysis & Composition Harness
• Execution Mode: Sequential Skill Orchestration

Registration

This skill is registered in the Claude Code skill system via:

1. File-based: Located at ~/.claude/skills/meditation-music-composition/SKILL.md
2. Project-based: Activated via project CLAUDE.md file
3. Trigger phrase: /meditation-music-composition [query]

Resolution

Claude resolves this skill when:

• User explicitly invokes /meditation-music-composition
• User query contains meditation/music therapy/brain-wave/entrainment keywords
• Context indicates composition or analysis of therapeutic audio
• Professional music therapy or psychoacoustic guidance is needed

Skill Architecture

Design Pattern: Sequential Skill Orchestration

This skill uses a hierarchical sequential orchestration pattern where a main harness (skills/main.md) coordinates 5 specialized sub-skills in strict order, with quality gate validation at each step.

User Input
    ↓
main.md (Harness Orchestrator)
    ├─→ Step 1: sub-gather-requirements
    ├─→ Step 2: sub-evidence-collector
    ├─→ Step 3: sub-core-analysis
    ├─→ Step 4: sub-knowledge-updater
    ├─→ Step 5: sub-advisor
    └─→ Step 6: Quality Gate Review (U1-U6 + G1-G4)
        ↓
Final Output

Sub-Skill Registry

| Sub-Skill | File | Purpose | Input Schema | Output Schema | |-----------|------|---------|--------------|----------------| | sub-gather-requirements | skills/sub-gather-requirements.md | Clarify analysis scope and constraints | UserQuery | RequirementsObject | | sub-evidence-collector | skills/sub-evidence-collector.md | Fetch authoritative domain data | RequirementsObject | EvidenceBundle | | sub-core-analysis | skills/sub-core-analysis.md | Compose evidence-based music specs | EvidenceBundle + Requirements | CompositionSpec | | sub-knowledge-updater | skills/sub-knowledge-updater.md | Query academic knowledge base | TopicKeywords | KnowledgeEvidence | | sub-advisor | skills/sub-advisor.md | Synthesize risk-disclosed conclusions | CompositionSpec + Evidence | FinalReport |

Input/Output Schemas

Input Schema (UserQuery)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "User query for meditation music composition",
  "required": ["query"],
  "properties": {
    "query": {
      "type": "string",
      "description": "Natural language query describing the composition or analysis request",
      "examples": [
        "Compose a 20-minute alpha-entrainment track for pre-surgery anxiety",
        "Design a Solfeggio-based session for stress relief with evidence caveats",
        "What binaural beat protocol is evidence-supported for insomnia?"
      ]
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi", "auto"],
      "default": "auto",
      "description": "Output language preference (auto-detect if 'auto')"
    },
    "constraints": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Specific constraints or limitations for the composition",
      "examples": ["headphone delivery only", "no Solfeggio frequencies", "max duration 30min"]
    },
    "target_audience": {
      "type": "string",
      "description": "Intended audience for the composition",
      "examples": ["clinical population", "general relaxation", "meditation practitioners"]
    },
    "delivery_format": {
      "type": "string",
      "enum": ["headphones", "speakers", "streaming", "any"],
      "default": "any",
      "description": "Delivery format for the composition"
    }
  }
}

Internal Schema (RequirementsObject)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Structured requirements object passed between sub-skills",
  "required": ["object", "therapeutic_goal", "language", "scope"],
  "properties": {
    "object": {
      "type": "string",
      "description": "Object of analysis/composition"
    },
    "therapeutic_goal": {
      "type": "string",
      "enum": ["sleep", "deep_meditation", "relaxation", "focus", "anxiety_reduction", "stress_reduction", "other"],
      "description": "Primary therapeutic goal"
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi"],
      "description": "Output language"
    },
    "scope": {
      "type": "string",
      "description": "Analysis scope and boundaries"
    },
    "constraints": {
      "type": "array",
      "items": {"type": "string"},
      "description": "User-specified constraints"
    },
    "timeframe": {
      "type": "string",
      "description": "Timeframe for composition or analysis"
    },
    "available_inputs": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Available input materials or data"
    },
    "target_audience": {
      "type": "string",
      "description": "Target audience for the composition"
    },
    "delivery_format": {
      "type": "string",
      "enum": ["headphones", "speakers", "streaming", "any"],
      "description": "Delivery format"
    },
    "contraindications_known": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Known contraindications or safety considerations",
      "examples": ["epilepsy", "tinnitus", "PTSD", "hearing_impairment", "pregnancy"]
    }
  }
}

Internal Schema (EvidenceBundle)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Bundle of authoritative evidence collected by evidence-collector",
  "required": ["current_data", "authoritative_docs", "degradation_level"],
  "properties": {
    "current_data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {"type": "string"},
          "data": {"type": "object"},
          "timestamp": {"type": "string", "format": "date-time"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4}
        }
      },
      "description": "Current real-time data with sources and timestamps"
    },
    "authoritative_docs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "source": {"type": "string"},
          "url": {"type": "string"},
          "date": {"type": "string"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4},
          "excerpt": {"type": "string"}
        }
      },
      "description": "Authoritative documents and standards"
    },
    "recent_news": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "source": {"type": "string"},
          "url": {"type": "string"},
          "date": {"type": "string"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4}
        }
      },
      "description": "Recent domain news and developments"
    },
    "reference_benchmarks": {
      "type": "array",
      "items": {"type": "object"},
      "description": "Reference benchmarks from knowledge base"
    },
    "degradation_level": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4,
      "description": "Data availability degradation level (0=full, 4=unavailable)"
    }
  }
}

Internal Schema (CompositionSpec)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Detailed music composition specification",
  "required": ["therapeutic_goal", "target_band", "entrainment_design", "arrangement_parameters"],
  "properties": {
    "therapeutic_goal": {
      "type": "string",
      "description": "Primary therapeutic goal"
    },
    "target_band": {
      "type": "string",
      "enum": ["delta", "theta", "alpha", "beta", "gamma"],
      "description": "Target brain-wave frequency band"
    },
    "target_frequency_range": {
      "type": "string",
      "description": "Target frequency range in Hz",
      "pattern": "^\\d+\\.?\\d*-\\d+\\.?\\d*\\s*Hz$"
    },
    "entrainment_design": {
      "type": "object",
      "required": ["method", "beat_frequency"],
      "properties": {
        "method": {
          "type": "string",
          "enum": ["binaural", "isochronic", "monaural", "music_only"],
          "description": "Entrainment method"
        },
        "carrier_frequencies": {
          "type": "array",
          "items": {"type": "number"},
          "description": "Carrier frequencies in Hz",
          "minItems": 1
        },
        "beat_frequency": {
          "type": "number",
          "description": "Beat frequency in Hz",
          "exclusiveMinimum": 0,
          "maximum": 40
        },
        "layer_level_db": {
          "type": "number",
          "description": "Layer level relative to musical layer (dB)",
          "minimum": -30,
          "maximum": 0
        },
        "formula": {
          "type": "string",
          "description": "Mathematical formula for entrainment calculation"
        }
      }
    },
    "arrangement_parameters": {
      "type": "object",
      "properties": {
        "tempo_bpm": {
          "type": "integer",
          "minimum": 40,
          "maximum": 120,
          "description": "Tempo in beats per minute"
        },
        "dynamic_range_db": {
          "type": "number",
          "maximum": 12,
          "description": "Dynamic range in decibels"
        },
        "timbres": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Primary timbres and instruments"
        },
        "harmonic_rhythm_bars": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16,
          "description": "Chords per harmonic change"
        },
        "tonality": {
          "type": "string",
          "description": "Key or mode"
        },
        "form": {
          "type": "string",
          "description": "Musical form structure"
        },
        "reverb_decay": {
          "type": "number",
          "description": "Reverb decay time in seconds"
        }
      }
    },
    "solfeggio_layer": {
      "type": "object",
      "properties": {
        "frequency": {
          "type": "number",
          "description": "Solfeggio frequency in Hz"
        },
        "traditional_claim": {
          "type": "string",
          "description": "Traditional claim associated with frequency"
        },
        "evidence_tier": {
          "type": "integer",
          "enum": [4],
          "description": "Evidence tier (always 4 for Solfeggio)"
        }
      }
    },
    "contraindications": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "condition": {"type": "string"},
          "adjustment": {"type": "string"},
          "rationale": {"type": "string"}
        }
      },
      "description": "Contraindication screening results and adjustments"
    },
    "outcomes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "metric": {"type": "string"},
          "expected_direction": {"type": "string"},
          "measurement_method": {"type": "string"}
        }
      },
      "description": "Measurable outcomes with metrics and methods"
    },
    "scenarios": {
      "type": "object",
      "properties": {
        "best": {"type": "string"},
        "base": {"type": "string"},
        "worst": {"type": "string"}
      },
      "description": "Best/base/worst case scenario descriptions"
    }
  }
}

Output Schema (FinalReport)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Final meditation music composition report",
  "required": ["report_header", "executive_summary", "inputs_scope", "evidence_collected", "composition_spec", "disclosure", "conclusion", "quality_gate_checklist"],
  "properties": {
    "report_header": {
      "type": "object",
      "required": ["title", "date", "version", "language", "domain"],
      "properties": {
        "title": {"type": "string"},
        "date": {"type": "string", "format": "date"},
        "version": {"type": "string"},
        "language": {"type": "string", "enum": ["en", "vi"]},
        "domain": {"type": "string"}
      }
    },
    "executive_summary": {
      "type": "string",
      "description": "2-3 sentence summary of verdict and headline action"
    },
    "inputs_scope": {
      "type": "object",
      "description": "Analysis inputs and scope definition"
    },
    "evidence_collected": {
      "type": "object",
      "description": "Collected evidence with sources, dates, and tier labels"
    },
    "composition_spec": {
      "$ref": "#/definitions/CompositionSpec",
      "description": "Core composition specification"
    },
    "academic_evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "citation": {"type": "string"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4},
          "relevance": {"type": "string"}
        }
      },
      "description": "Academic and research evidence from knowledge base"
    },
    "disclosure": {
      "type": "object",
      "required": ["coverage", "limitations", "safety_advisories"],
      "properties": {
        "coverage": {"type": "string"},
        "limitations": {"type": "array", "items": {"type": "string"}},
        "safety_advisories": {"type": "array", "items": {"type": "string"}}
      },
      "description": "Mandatory disclosure section"
    },
    "conclusion": {
      "type": "object",
      "required": ["verdict", "key_risks", "evidence_chain", "remediation"],
      "properties": {
        "verdict": {
          "type": "string",
          "enum": [
            "Evidence-Based Composition",
            "Promising (emerging evidence)",
            "Limited Evidence (traditional)",
            "Inconclusive"
          ]
        },
        "key_risks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "risk": {"type": "string"},
              "probability": {"type": "string"},
              "impact": {"type": "string"}
            }
          }
        },
        "evidence_chain": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Evidence traceability chain"
        },
        "remediation": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Remediation actions and next steps"
        }
      },
      "description": "Final conclusion with verdict and recommendations"
    },
    "quality_gate_checklist": {
      "type": "object",
      "description": "Quality gate pass/fail checklist with limitations"
    }
  }
}

Tool Definitions

Required Tools

| Tool | Purpose | Usage Pattern | Sub-Skills | |------|---------|---------------|------------| | WebSearch | Live domain research | Search Cochrane, AMTA, academic sources | evidence-collector, core-analysis, knowledge-updater | | WebFetch | Document retrieval | Fetch papers, guidelines, standards | evidence-collector | | Read | Knowledge base access | Read SECOND-KNOWLEDGE-BRAIN.md, reference files | All sub-skills | | Write | Knowledge updates | Append to knowledge base via knowledgeupdater.py | knowledge-updater | | Bash | Script execution | Run knowledgeupdater.py pipeline | main (knowledge updates) | | Skill | Sub-skill invocation | Orchestrate 5 sub-skills sequentially | main |

Tool Usage Protocols

WebSearch Protocol

# When to use WebSearch
- Gap-filling when knowle

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** [dungnotnull/meditation-music-composition-agent-skill](https://github.com/dungnotnull/meditation-music-composition-agent-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.