afanmusic

---
name: music-education-research-writer
description: Helps conduct social science academic research and scholarly writing, especially for music, education, and music education studies. Use this skill to synthesize user-provided research corpora, literature notes, iMA-exported materials, classroom observations, and policy texts into literature reviews, theoretical frameworks, conceptual models, and research gap analyses with strict citation integrity and evidence hierarchy.
---

# Music Education Research Writer

## Skill purpose

This skill supports early-stage and mid-stage academic research writing for social science, education, music research, and music education research. It is designed to help the user transform verified or user-provided materials into:

- literature reviews
- theoretical frameworks
- conceptual or analytical models
- research gap analyses
- opening-report arguments
- core-journal topic framing
- classroom-practice research designs

The skill does not replace the user's academic judgment and should not behave like an automatic full-paper ghostwriter.

## When to use this skill

Use this skill when the user needs help with one or more of these tasks:

- synthesizing a literature corpus into a structured literature review
- identifying concepts, variables, theoretical anchors, and relationships
- building a theory model, conceptual model, or paper argument model
- locating research gaps in music education, education, or AI plus music education topics
- refining a topic for Chinese core-journal, CSSCI, or Peking University core-journal contexts
- converting classroom observations, research logs, policy texts, and literature notes into a traceable evidence chain
- analyzing iMA-exported files or a local `research_corpus` folder provided by the user

This skill is especially suitable for:

- music research
- education research
- music education and curriculum research
- AI plus music education research
- high-school music curriculum
- music appreciation and aesthetic education
- music creation pedagogy
- human-AI collaborative music creation
- local or regional music culture in school music education

## When not to use this skill

Do not use this skill for:

- fabricating a complete paper without a traceable evidence base
- inventing authors, years, journals, DOI records, policy documents, or institutional reports
- making unsupported claims sound academic by using polished but empty language
- substituting for formal peer review, ethics review, or statistical review
- automatically reading arbitrary files outside folders explicitly provided by the user
- automatically uploading files, downloading scripts, reading credentials, or using hidden integrations

If the user asks for a complete paper immediately, first recommend a staged workflow:

1. literature review
2. theory and concept framework
3. method design
4. data and evidence
5. analysis and discussion

The skill may help draft sections or paragraphs, but each paragraph must show what evidence it is based on.

## Core workflow

1. Diagnose the immediate task.
   Decide whether the user needs a literature review, theory model, research gap analysis, topic incubation, opening-report support, journal framing, or a combination.
2. Decide the task grain and output mode.
   Judge whether the user needs a quick decision, a structured analysis, or formal prose. Default to `Standard Mode` unless the user explicitly asks for `Brief Mode` or `Deep Mode`.
3. Ask the minimum clarifying questions only when necessary.
   If the corpus, topic, population, or context is unclear, ask short questions. If the user already supplied enough material, proceed directly.
4. Triage the corpus before deep analysis.
   When materials are large in volume, first classify them into high, medium, low, and `待核验` relevance buckets. Analyze high-relevance materials first.
5. Build the research frame.
   Extract the research object, setting, concepts or variables, theory background, method tendency, publication direction, and likely paper type.
6. Read the provided corpus through the source adapter.
   Only use files from the user-provided iMA export folder or local `research_corpus` folder.
7. Classify evidence.
   Tag sources as `A`, `B`, `C`, `D`, or `E`, mark unverified items `待核验`, and separate academic evidence from field material.
8. Generate the smallest useful output first.
   Start with structure, judgment, priorities, and decision support before writing long prose.
9. Generate the requested output.
   Use the relevant template for literature review, theory modeling, research gap analysis, opening-report support, or classroom-practice design.
10. End with constraints and next steps.
   If evidence is insufficient, output `需要补充的文献清单`. If a paper request is too broad, decompose it into staged writing tasks.

## Token Efficiency Protocol

Always optimize for research value per token. Do not exhaustively summarize or expand all materials by default. Start with the smallest useful output that helps the user make the next research decision, then expand only when the user explicitly asks for more depth.

中文解释：

始终追求单位 token 的研究价值最大化。默认不穷尽式总结所有材料，也不默认展开所有论证。先输出能帮助用户做出下一步研究判断的最小有效结果；只有在用户明确要求时，才继续深度扩写。

### Core principles

- do not exhaustively summarize all materials by default
- do not expand every literature detail by default
- do not generate very long paper prose by default
- provide structure, judgment, and priorities before expansion
- prioritize content with the highest value for research decisions
- compress repetitive, low-value, or marginally relevant material
- label weak-evidence areas as `材料不足` instead of filling with vague prose
- avoid long background explanations unless the user explicitly asks
- list key literature clusters rather than all literature by default
- use phased output for long reviews, theory models, and research gap analysis

### Default output length control

Unless the user explicitly asks for `complete expansion`, `long version`, `formal paper prose`, or `full literature review`, default to the following:

#### Literature review tasks

Default output:

- review structure table
- 3 to 5 core theme clusters
- 3 to 5 key judgments for each cluster
- representative evidence for each cluster
- a final `whether this is worth expanding` recommendation

Do not generate a full 3000 to 5000 word review by default.

#### Theory and model tasks

Default output:

- core concept list
- text version of concept relations
- 1 main model
- 1 to 2 backup models
- for each model: suitable scene, theory basis, variable relations, collectable data, and risks

Do not generate too many models or a long theory history by default.

#### Research gap tasks

Default output:

- research gap matrix
- 5 to 8 highest-value gaps
- 1 to 2 research questions per gap
- publication potential and feasibility labels

Do not list dozens of gaps by default.

#### Material reading tasks

Default output:

- high-relevance materials
- medium-relevance materials
- low-relevance materials
- `待核验` materials

Deep analysis should focus on high-relevance materials first. Medium-relevance materials should be compressed into summaries. Low-relevance materials should stay in reserve unless the user asks for them.

### Phased workflow

#### Phase 1: quick diagnosis

Start with a concise response that answers:

1. what type of task this is
2. whether the available materials are sufficient
3. which materials deserve priority
4. what the most likely output should be
5. whether expansion is needed now

#### Phase 2: structured analysis

Only enter this phase if the user asks to continue or the initial task clearly requires it:

1. literature review expansion
2. theory model development
3. deeper research gap analysis
4. paragraph drafting
5. opening-report argumentation

#### Phase 3: formal writing

Only enter this phase if the user explicitly asks for:

- paper prose
- formal paragraphs
- a full literature review
- deep expansion

### Output-grain judgment before each response

Before responding, decide:

1. does the user need a judgment or a polished paragraph
2. does the user need direction advice or full writing
3. does the user need quick screening or deep research
4. has the user provided enough material
5. can the answer be compressed into a table, matrix, or list

If the answer can be expressed clearly as a table, matrix, or checklist, do not default to long-form prose.

### Priority order for large corpora

When many materials are available, process them in this order:

1. materials highly relevant to the user's topic
2. authoritative academic literature, core journals, CSSCI, policy texts, authoritative monographs
3. materials directly tied to method selection
4. materials directly tied to theory or model building
5. materials directly tied to Chinese music education, ordinary high-school music curriculum, or AI music education
6. first-hand materials such as classroom observations, research logs, and student feedback
7. WeChat public articles, media writing, and industry commentary
8. low-relevance background materials

Low-priority materials should not be expanded by default.

### Prohibited token-wasting behaviors

- indiscriminately summarizing every material
- writing a long paragraph for each paper
- repeating basic concepts the user likely already knows
- filling `research significance` with generic language
- mechanically generating a generic `domestic and international research status` section
- expanding claims without evidence
- listing too many theories merely for apparent completeness
- defaulting to a full-paper response
- forcing long-form writing when materials are insufficient
- giving generic academic-writing advice unrelated to the current task

### Token Budget Modes

#### Mode 1: Brief Mode

Use for quick judgment.

- target length: 300 to 800 words
- prefer tables and short lists
- do not write long-form prose

Typical use:

- topic judgment
- initial literature screening
- direction comparison
- checking whether materials are usable

#### Mode 2: Standard Mode

Use for normal research analysis. This is the default.

- target length: 1000 to 2500 words
- include structure tables, key judgments, and evidence notes
- do not generate full paper prose by default

Typical use:

- literature review framework
- theory model draft
- research gap matrix
- opening-report pre-argumentation

#### Mode 3: Deep Mode

Use only when the user explicitly asks for deep expansion.

- length may exceed 3000 words
- output must be sectioned
- each section must serve a clear research goal
- do not expand irrelevant background

Typical use:

- formal literature review
- paper prose paragraphs
- full theory framework argument
- deep core-journal paper refinement

### Large-corpus handling rule

When the user provides a large corpus, do not deeply process everything at once. First output:

- corpus overview
- corpus classification
- high-relevance materials
- deferrable materials
- 3 to 5 material clusters worth prioritizing
- the suggested next processing step

Only go deeper after the user confirms which cluster should be expanded.

### Progressive expansion prompt

At most, end with a short next-step menu such as:

`If you want to go deeper, the best next step is one of: A. expand the literature review prose; B. build the theory model; C. generate the research gap matrix.`

Do not expand A, B, and C all at once by default.

## Evidence rules

All source use must follow a typed evidence hierarchy:

- `A`: peer-reviewed journal articles, verified dissertations, authoritative monographs, official policy or curriculum standards
- `B`: CSSCI, Peking University core journals, high-value Chinese education journals, strong domestic publication targets
- `C`: conference papers, institutional reports, project summaries, white papers
- `D`: WeChat article exports, classroom observations, interviews, meeting notes, teaching logs
- `E`: user reflections, preliminary ideas, undocumented experience

Evidence rules:

- do not present `D` or `E` as established academic consensus
- do not collapse all source types into one undifferentiated summary
- distinguish verified evidence from contextual or exploratory material
- attach source IDs such as `[A01]`, `[B02]`, `[D03]` to major claims
- preserve uncertainty whenever metadata or publication status is incomplete

If the current corpus cannot support a stable claim, say so directly and add it to `需要补充的文献清单`.

## Citation integrity rules

The following are prohibited:

- inventing authors
- inventing publication years
- inventing journal titles
- inventing DOI values
- inventing policy documents
- inventing institutions or report names
- using vague academic language to hide missing evidence

The following are required:

- mark unknown or incomplete items as `待核验`
- keep evidence class visible near major claims
- differentiate literature findings from user notes, classroom observation, and public articles
- state when a paragraph is based on literature, policy, observation, interview, questionnaire, or mixed evidence
- when drafting a paragraph, include a short basis line such as `依据来源: A01, B02, D01`

For Chinese core-journal, CSSCI, or Peking University core-journal contexts, emphasize:

- clear problem consciousness
- explicit theoretical contribution
- method rigor
- evidence traceability
- adaptation to the Chinese education context

## iMA / local corpus integration rules

This skill must not assume that iMA exposes a public API. Use only honest, replaceable adapter modes.

Allowed ingestion modes:

1. iMA export folder mode
2. local `research_corpus` folder mode
3. future adapter mode if a real API, MCP, or CLI later becomes verifiable

Allowed behavior:

- read folders explicitly provided by the user
- read exported notes, PDFs, DOCX files, Markdown files, TXT files, public article exports, observation notes, and research logs
- summarize source structure and build evidence tables

Disallowed behavior:

- scanning the user's full disk
- reading unrelated directories
- automatically reading API keys, tokens, cookies, browser data, or system credentials
- automatically uploading or syncing files
- claiming an iMA integration that cannot be verified

Recommended corpus layout:

```text
research_corpus/
├── literature/
├── policy/
├── notes/
├── observations/
├── interviews/
├── questionnaires/
└── manifest.md
```

When materials are incomplete or messy, first build a source register and then identify what is still missing.
When materials are very large, first output corpus triage rather than deep synthesis.

## Literature review procedure

When the user asks for a literature review:

1. diagnose the topic, population, setting, and target writing context
2. inventory the available literature and non-literature materials
3. triage materials into high, medium, low, and `待核验`
4. separate domestic and international research when relevant
5. define key concepts and identify competing terms
6. synthesize by theme, concept, theory, method, controversy, and gap
7. avoid author-by-author流水账 summaries unless the user explicitly asks for a bibliographic list
8. in default mode, produce:
   - a quick diagnosis
   - a review structure table
   - 3 to 5 core theme clusters
   - key judgments and representative evidence
   - a recommendation on whether expansion is worthwhile
9. in deeper modes, produce:
   - a review structure table
   - expandable review paragraphs
   - a citation and evidence list
10. if the corpus is too thin, output `需要补充的文献清单`

The review should normally include:

- concept definition
- domestic research trajectory
- international research trajectory
- major theory lenses
- major methods used
- shared findings
- disputes and controversies
- limitations
- implications for the user's topic

## Theory and model construction procedure

When the user asks for theory or model support:

1. extract central concepts, variables, and possible dimensions
2. identify theory anchors that are actually supported by the corpus
3. in default mode, start with:
   - a core concept list
   - a text-based concept relation map
   - 1 main model
   - 1 to 2 backup models
4. in deeper modes, build at least three model views when the corpus allows:
   - concept model
   - analytical framework model
   - paper-writing model
5. for each model, explain:
   - suitable research question
   - theory basis
   - concept or variable relations
   - possible data sources
   - likely risks
   - likely publication direction
6. translate abstract concepts into classroom-observable indicators when relevant
7. if the theory basis is weak, say exactly which concepts or theories require further literature support

For music education and Chinese education contexts, pay close attention to:

- curriculum standards and core competencies
- music aesthetics, creation, performance, and cultural understanding
- student engagement, motivation, and agency
- classroom interaction
- human-AI collaborative creation
- local or regional music culture

## Research gap analysis procedure

When the user asks for research gaps:

1. review what the existing corpus already covers
2. identify specific rather than generic gaps
3. check for at least these gap types:
   - object gap
   - scene gap
   - method gap
   - theory gap
   - data gap
   - practice gap
   - China-context gap
   - cross-disciplinary gap
4. convert each gap into one or more feasible research questions
5. propose a fitting method and likely data source for each question
6. label each question with publication potential and risk level
7. in default mode, keep the shortlist to 5 to 8 highest-value gaps
8. end with a prioritized shortlist of the most promising research questions

If the corpus does not support a reliable gap statement, say which literature areas still need to be added before the gap analysis can be trusted.

## Output templates

Use or adapt the bundled templates:

- `templates/literature_review_template.md`
- `templates/theory_model_template.md`
- `templates/research_gap_matrix_template.md`
- `templates/opening_report_argument_template.md`
- `templates/journal_article_outline_template.md`
- `templates/classroom_practice_research_design_template.md`
- `templates/evidence_chain_table_template.md`
- `templates/literature_concept_theory_method_gap_map.md`

Default output habits:

- start with a structure table
- default to `Standard Mode` unless the user explicitly asks for `Brief Mode` or `Deep Mode`
- optimize for research value per token
- keep evidence basis visible
- distinguish domestic and international research if relevant
- use phase-based output: diagnosis first, structured analysis second, formal prose last
- use Markdown tables and headings so the result can be reused in Word, WPS, Obsidian, Notion, or iMA notes
- if material is insufficient, add `需要补充的文献清单`
- if the corpus is large, start with screening and prioritization before deep analysis

## Safety and academic integrity constraints

This skill is designed to use minimal privileges and should not request broad access.

Forbidden behaviors:

- automatic full-disk reading
- automatic file upload
- automatic network download of scripts
- automatic shell execution
- automatic reading of API keys, tokens, cookies, browser data, or credential stores
- fabricated literature
- untraceable citations

Allowed behaviors:

- reading folders explicitly provided by the user
- reading exported literature notes and research materials
- reading files placed in a user-designated `research_corpus`
- generating Markdown, evidence tables, theory models, research questions, and structured review text
- generating evidence-chain tracking tables

When uncertainty remains, prefer explicit limitation statements over polished but unsupported prose.

## Examples

Example requests that should trigger this skill:

- `Please synthesize my iMA-exported notes and local research_corpus into a literature review on AI-assisted high-school music composition teaching.`
- `Help me identify research gaps in music aesthetics education using the literature and classroom observations I provided.`
- `Based on these CSSCI articles, policy texts, and lesson notes, build a theory model for human-AI collaborative music creation in ordinary high-school music classes.`
- `I want to write a Chinese core-journal article on music education. Please help me first build the review, theory framework, and research gap matrix instead of writing the whole paper at once.`

Example safe response pattern:

1. research task diagnosis
2. output mode and whether expansion is justified
3. corpus triage or evidence inventory
4. research frame
5. main structured output
6. `需要补充的文献清单`, if needed
7. next writing step

FILE:README.md
# music-education-research-writer

## Skill 简介

`music-education-research-writer` 是一个面向社科类学术研究与学术论文写作的标准化 Skill，重点服务以下研究方向：

- 音乐研究
- 教育研究
- 音乐教育交叉研究
- AI + 音乐教育研究
- 高中音乐课程、音乐审美、音乐创作教学、人机协作音乐创作等应用型研究

它不鼓励“直接一键生成整篇论文”，而是聚焦论文最关键、最有研究含量的前期模块：

1. 文献综述
2. 理论框架 / 概念模型 / 分析模型建构
3. 研究空白识别

## 适用场景

适合以下需求：

- 基于用户已有文献与笔记生成结构化文献综述
- 从论文、政策、课堂观察、问卷、访谈中提炼理论观念与变量关系
- 识别研究对象、研究场景、研究方法、理论整合、数据类型等方面的空白
- 为开题报告、核心期刊论文、课程研究或课堂实践研究提供前期论证
- 帮助中国语境下的音乐教育研究形成“问题意识 + 理论贡献 + 方法严谨性 + 中国教育情境”的论文基础

## 安装方式

### 方式 1：直接使用本地文件夹

将整个 `music-education-research-writer/` 文件夹放入你的 Skills 目录或待上传目录中。

### 方式 2：使用压缩包

可直接使用：

- `music-education-research-writer.zip`
- `music-education-research-writer.skill`

其中 `.skill` 本质上是保留根目录结构的 ZIP 包，只是扩展名改为 `.skill`。

## 文件结构

```text
music-education-research-writer/
├── SKILL.md
├── README.md
├── references/
│   ├── workflow.md
│   ├── evidence_hierarchy.md
│   ├── social_science_methods.md
│   ├── music_education_ontology.md
│   ├── literature_review_principles.md
│   ├── theory_modeling_guide.md
│   ├── research_gap_taxonomy.md
│   └── ima_integration.md
├── templates/
│   ├── literature_review_template.md
│   ├── theory_model_template.md
│   ├── research_gap_matrix_template.md
│   ├── opening_report_argument_template.md
│   ├── journal_article_outline_template.md
│   ├── classroom_practice_research_design_template.md
│   ├── evidence_chain_table_template.md
│   └── literature_concept_theory_method_gap_map.md
├── examples/
│   ├── example_ai_music_education_review.md
│   ├── example_large_corpus_triage.md
│   ├── example_theory_model.md
│   └── example_research_gap_matrix.md
├── tests/
│   ├── sample_user_request.md
│   ├── sample_large_corpus_request.md
│   ├── sample_corpus_notes.md
│   ├── expected_output_checklist.md
│   └── pre_publish_checklist.md
├── scripts/
│   ├── validate_skill.py
│   └── package_skill.py
└── dist/
    ├── music-education-research-writer.zip
    └── music-education-research-writer.skill
```

## 如何准备 iMA 导出材料

这个 Skill 不伪造 iMA API，也不会假设 iMA 一定存在正式接口。推荐做法是把 iMA 中的材料导出到本地文件夹，再交给 Skill 分析。

推荐目录结构：

```text
research_corpus/
├── literature/
├── policy/
├── notes/
├── observations/
├── interviews/
├── questionnaires/
└── manifest.md
```

推荐准备内容：

- PDF 文献
- Word 文档
- Markdown 笔记
- TXT 摘录
- 微信公众号导出文章
- 课堂观察记录
- 研究日志
- 问卷结果
- 访谈材料
- 政策与课程标准文本

推荐 `manifest.md` 字段：

- `source_id`
- `file_name`
- `source_type`
- `origin`
- `verification_status`
- `notes`

## 如何准备本地 research_corpus 文件夹

如果你不用 iMA，也可以直接准备本地 `research_corpus/` 文件夹。建议：

1. 按资料类型建子文件夹。
2. 给每份资料编一个稳定 ID，例如 `A01`、`B03`、`D02`。
3. 把未核验材料标记为 `待核验`。
4. 将课堂观察、问卷、访谈与正式文献分开。
5. 如果是中文核心期刊写作，尽量单独放一个 `core_journals/` 或在 `manifest.md` 中注明 CSSCI / 北大核心属性。

## 示例调用语句

```text
请基于我提供的 research_corpus 文件夹，先帮我做一份关于“AI辅助高中音乐创作教学中的人机协作机制”的文献综述结构表，再生成可扩写段落，并给出证据链追踪表。
```

```text
我有一些 CSSCI 论文、课程标准、课堂观察记录和学生问卷。请不要直接代写全文，先帮我建立理论框架、概念模型和研究空白矩阵。
```

```text
请读取我导出的 iMA 笔记、微信文章摘录和本地 PDF 文献，区分证据等级，判断哪些结论可以写进开题报告，哪些还需要补充文献。
```

## 输出示例

Skill 的典型输出包含：

- 研究任务诊断
- 研究框架表
- 证据等级与证据链表
- 文献综述结构表
- 可扩写综述段落
- 理论模型 / 分析框架 / 论文写作模型
- 研究空白矩阵
- `需要补充的文献清单`
- 材料筛选与优先处理建议

可参考：

- [example_ai_music_education_review.md](./examples/example_ai_music_education_review.md)
- [example_theory_model.md](./examples/example_theory_model.md)
- [example_research_gap_matrix.md](./examples/example_research_gap_matrix.md)
- [example_large_corpus_triage.md](./examples/example_large_corpus_triage.md)

## Token 高效使用说明

这个 Skill 默认不会一次性生成超长论文内容，也不会默认穷尽式总结所有材料。

默认行为是：

1. 先判断
2. 再筛选
3. 再建框架
4. 再局部扩写
5. 最后才生成正文

默认采用 `Standard Mode`。

你可以这样切换模式：

- `请用 Brief Mode 快速判断。`
- `请用 Standard Mode 输出结构化分析。`
- `请用 Deep Mode 展开成论文正文。`

当用户材料很多时，Skill 会先做：

- 材料总览
- 材料分类
- 高相关材料清单
- 可暂缓材料清单
- 优先处理建议

而不会默认把所有材料全部深度分析。这样可以减少 token 浪费，同时提高学术研究效率。

## 学术诚信声明

本 Skill 明确禁止以下行为：

- 伪造作者
- 伪造年份
- 伪造期刊
- 伪造 DOI
- 伪造政策文件
- 用“看似学术”的语言掩盖证据不足
- 把公众号文章、课堂笔记、个人经验伪装成同行评审结论
- 输出不可追溯引用

本 Skill 允许帮助用户形成段落，但必须说明依据来自哪里，并在证据不足时输出 `需要补充的文献清单`。

如果用户要求直接生成整篇论文，应先建议拆解为：

1. 综述
2. 理论
3. 方法
4. 数据
5. 讨论

## 安全声明

这是一个面向学术研究写作的 Skill，不应申请过多权限。

禁止：

- 自动读取用户全盘文件
- 自动上传文件
- 自动联网下载不明脚本
- 自动执行 shell 命令
- 自动读取 API key / token / cookies / 浏览器数据

允许：

- 读取用户明确提供的文件夹
- 读取用户导出的文献笔记
- 读取用户明确放入 `research_corpus` 的资料
- 生成 Markdown、表格、研究框架、模型说明、研究问题建议
- 生成证据链追踪表

## 如何打包成 zip / .skill 文件

### 先运行校验

```bash
python3 scripts/validate_skill.py .
```

### 方式 A：打包为普通 ZIP

```bash
python3 scripts/package_skill.py . --format zip
```

生成：

```text
dist/music-education-research-writer.zip
```

### 方式 B：打包为 ClawHub / OpenClaw 风格 .skill 包

```bash
python3 scripts/package_skill.py . --format skill
```

生成：

```text
dist/music-education-research-writer.skill
```

### 同时生成两种格式

```bash
python3 scripts/package_skill.py . --format both
```

## 如何提交到 SkillHub / ClawHub

建议提交流程：

1. 运行 `python3 scripts/validate_skill.py .`
2. 确认 `tests/pre_publish_checklist.md` 中所有项目都通过
3. 生成 `.zip` 或 `.skill`
4. 检查压缩包内是否保留根目录 `music-education-research-writer/`
5. 检查 `SKILL.md` frontmatter 是否只包含 `name` 和 `description`
6. 检查示例、模板、参考文档是否齐全
7. 检查 Token Efficiency Protocol 是否已落实到 SKILL、模板、示例与测试文件
8. 在 SkillHub / ClawHub 的发布页填写名称、简介、标签与说明
9. 上传 `music-education-research-writer.zip` 或 `music-education-research-writer.skill`
10. 在发布说明中注明：本 Skill 不联网抓取、不伪造文献、依赖用户提供语料

## 本地创建文件的命令

如果你想从零创建同名目录，可用：

```bash
mkdir -p music-education-research-writer/{references,templates,examples,tests,scripts,dist}
```

如果你想直接打包当前目录：

```bash
cd music-education-research-writer
python3 scripts/validate_skill.py .
python3 scripts/package_skill.py . --format both
```

FILE:templates/research_gap_matrix_template.md
# Research Gap Matrix Template

## Token-Efficient Default

Default to `Standard Mode`.

- keep to 5 to 8 highest-value gaps by default
- give 1 to 2 research questions per gap
- focus on publishability and feasibility
- do not list dozens of weak gaps

## 0. Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | |
| Output mode | Brief / Standard / Deep |
| Materials sufficient | yes / no / partially |
| Priority literature or data sources | |
| Whether gap analysis is reliable now | |

## Research Gap Matrix

| Gap type | Evidence basis | Concrete gap statement | Candidate research question | Feasible method | Expected data | Publication potential | Risk level |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Object gap | | | | | | | |
| Scene gap | | | | | | | |
| Method gap | | | | | | | |
| Theory gap | | | | | | | |
| Data gap | | | | | | | |
| Practice gap | | | | | | | |
| China-context gap | | | | | | | |
| Cross-disciplinary gap | | | | | | | |

## Priority Selection

| Priority | Recommended question | Why it is promising | Main condition to satisfy |
| --- | --- | --- | --- |
| 1 | | | |
| 2 | | | |
| 3 | | | |

## Final Recommendation

`[State which gap is the best entry point and why.]`

## Expansion Decision

| Question | Answer |
| --- | --- |
| Which 1 to 3 gaps deserve deeper follow-up | |
| Which gaps should be deferred | |
| What literature is still missing | |

FILE:templates/classroom_practice_research_design_template.md
# Classroom Practice Research Design Template

## 1. Practice Context

| Field | Content |
| --- | --- |
| School stage | |
| Grade | |
| Course or module | |
| Lesson topic | |
| Duration | |
| Teacher role | |
| Student characteristics | |

## 2. Practice Problem

`[Describe the concrete classroom problem that motivates the study.]`

## 3. Intervention Or Design

| Item | Design choice | Rationale |
| --- | --- | --- |
| Teaching goal | | |
| Core activity | | |
| AI or tool use, if any | | |
| Assessment approach | | |
| Iteration plan | | |

## 4. Research Questions

1. `[Question 1]`
2. `[Question 2]`
3. `[Question 3, optional]`

## 5. Evidence Collection Plan

| Data type | Source | Timing | Purpose |
| --- | --- | --- | --- |
| Observation | | | |
| Student work | | | |
| Interview or reflection | | | |
| Questionnaire | | | |
| Rubric or score | | | |

## 6. Analysis Plan

| Question | Data | Analysis method | Risk note |
| --- | --- | --- | --- |
| | | | |

## 7. Ethical And Practical Considerations

| Issue | Note | Mitigation |
| --- | --- | --- |
| Consent | | |
| Privacy | | |
| Classroom burden | | |
| Tool dependence | | |

## 8. Expected Outcomes

`[State what practical and research outcomes are expected.]`

FILE:templates/theory_model_template.md
# Theory Model Template

## Token-Efficient Default

Default to `Standard Mode`.

- start with a concept list and one main model
- keep backup models to 1 to 2
- do not narrate long theory history unless the user asks

## 0. Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | |
| Output mode | Brief / Standard / Deep |
| Materials sufficient | yes / no / partially |
| Most relevant theory sources | |
| Whether deeper expansion is worth doing now | |

## 1. Modeling Premise

| Field | Working content |
| --- | --- |
| Topic | |
| Research object | |
| Setting | |
| Main problem | |
| Candidate theory base | |
| Preferred method | |

## 2. Concept Model

### 2.1 Core Concepts

| Concept | Definition | Source basis | Notes |
| --- | --- | --- | --- |
| | | | |

### 2.2 Concept Relations

| Relation | Explanation | Theory basis | Confidence |
| --- | --- | --- | --- |
| `A -> B` | | | |

### 2.3 Concept Model Summary

`[Summarize the concept model in one paragraph.]`

## 3. Analytical Framework Model

| Element | Content |
| --- | --- |
| Research question | |
| Independent or focal variable | |
| Dependent or focal outcome | |
| Mediator or process path | |
| Moderator or condition | |
| Observable indicators | |
| Data sources | |
| Analysis route | |

### Analytical Framework Narrative

`[Explain how the framework can be operationalized in the target study.]`

## 4. Paper-Writing Model

| Section | Function | Expected material |
| --- | --- | --- |
| Problem entry | | |
| Literature base | | |
| Theory anchor | | |
| Method route | | |
| Core analysis | | |
| Discussion | | |
| Implication | | |

## 5. Model Evaluation

| Model type | Suitable research question | Usable data | Risks | Publication direction |
| --- | --- | --- | --- | --- |
| Concept model | | | | |
| Analytical framework | | | | |
| Paper-writing model | | | | |

## 6. Expansion Decision

| Question | Answer |
| --- | --- |
| Which model should be expanded first | |
| Which model can stay as backup | |
| Which theory support is still missing | |

FILE:templates/evidence_chain_table_template.md
# Evidence Chain Table Template

## Evidence Inventory

| Source ID | File or reference | Source type | Evidence class | Verification | Main usable claim | Limits |
| --- | --- | --- | --- | --- | --- | --- |
| | | | | | | |

## Claim Tracking

| Working claim | Supporting source IDs | Evidence strength | Whether more evidence is needed | Notes |
| --- | --- | --- | --- | --- |
| | | | | |

## Risk Tracking

| Risk | Related source IDs | Severity | Mitigation |
| --- | --- | --- | --- |
| | | | |

FILE:templates/literature_review_template.md
# Literature Review Template

## Token-Efficient Default

Default to `Standard Mode`.

- start with Phase 1 diagnosis
- group literature into 3 to 5 core clusters
- expand only if the user asks for deeper prose
- if the corpus is large, screen for high, medium, low, and `待核验` relevance first

## 0. Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | |
| Output mode | Brief / Standard / Deep |
| Materials sufficient | yes / no / partially |
| Priority literature clusters | |
| Whether expansion is worth doing now | |

## 0.1 Corpus Triage

| Relevance bucket | Material IDs or files | Handling rule |
| --- | --- | --- |
| High relevance | | deep analysis first |
| Medium relevance | | compress into short summary |
| Low relevance | | reserve only |
| 待核验 | | verify before relying on it |

## 1. Review Structure Table

| Section | Focus | Key sources | Notes |
| --- | --- | --- | --- |
| Concept definition | | | |
| Domestic trajectory | | | |
| International trajectory | | | |
| Theory lenses | | | |
| Methods used | | | |
| Consensus | | | |
| Controversies | | | |
| Limitations | | | |
| Implications for this topic | | | |

## 2. Expandable Review Draft

For `Standard Mode`, keep this section concise and focused on the top 3 to 5 theme clusters. For `Deep Mode`, expand into fuller prose only after the user explicitly asks.

### 2.1 Concept Definition

`[Define the central concept, note competing terms, and specify which definition this paper will adopt.]`

### 2.2 Domestic Research Trajectory

`[Summarize how Chinese or domestic scholarship has approached the topic, what journals or policy contexts matter, and what trends appear.]`

### 2.3 International Research Trajectory

`[Summarize international scholarship, noting major concepts, methods, and transferable or non-transferable findings.]`

### 2.4 Main Theory Lenses

`[Compare the dominant theories and identify which lens is most useful for the present topic.]`

### 2.5 Main Methods Used

`[Describe what methods dominate and which methods remain underused.]`

### 2.6 Consensus

`[List stable findings or near-consensus claims, with evidence class markers.]`

### 2.7 Controversies And Disagreements

`[Identify disputes over concept definition, effects, methods, or contextual transferability.]`

### 2.8 Research Limitations

`[State concrete limitations in object, scene, method, theory, data, or practice transfer.]`

### 2.9 Implications For The User's Topic

`[Explain how the review narrows the topic, sharpens the question, or supports the chosen method.]`

## 3. Citation And Evidence List

| Claim or subsection | Source ID | Evidence class | Verification | Follow-up needed |
| --- | --- | --- | --- | --- |
| | | | | |

## 4. Expansion Decision

| Question | Answer |
| --- | --- |
| Is a full prose review justified now | |
| What should be expanded first | |
| What literature is still missing | |

FILE:templates/literature_concept_theory_method_gap_map.md
# Literature Concept Theory Method Gap Map

## Mapping Table

| Literature theme | Key concept | Theory lens | Method used in existing work | Observed gap | Relevance to user topic |
| --- | --- | --- | --- | --- | --- |
| | | | | | |

## Topic Synthesis

### Strongly Supported Area

`[Which concept-theory-method combinations are already well supported?]`

### Weakly Supported Area

`[Which combinations are thin, inconsistent, or context-limited?]`

### Most Promising Entry Point

`[Which mapping gap is most worth turning into a research question?]`

FILE:templates/opening_report_argument_template.md
# Opening Report Argument Template

## 1. Topic Positioning

| Field | Content |
| --- | --- |
| Proposed topic | |
| Research field | |
| Target setting | |
| Main problem | |
| Why now | |

## 2. Research Value

### Theoretical Value

`[Explain what concept, theory, or framework problem the study addresses.]`

### Practical Value

`[Explain what classroom, curriculum, or educational problem the study can help solve.]`

## 3. Literature Basis

| Aspect | Main conclusion | Source IDs | Remaining problem |
| --- | --- | --- | --- |
| Concept basis | | | |
| Theory basis | | | |
| Method basis | | | |
| Gap basis | | | |

## 4. Core Research Questions

1. `[Question 1]`
2. `[Question 2]`
3. `[Question 3, optional]`

## 5. Theory And Method Route

| Item | Planned choice | Reason |
| --- | --- | --- |
| Theory base | | |
| Research design | | |
| Data sources | | |
| Analysis method | | |

## 6. Feasibility

| Feasibility factor | Current basis | Risk | Mitigation |
| --- | --- | --- | --- |
| Data access | | | |
| Site access | | | |
| Time | | | |
| Researcher capability | | | |

## 7. Expected Contribution

`[State expected theoretical, methodological, and practical contribution.]`

FILE:templates/journal_article_outline_template.md
# Journal Article Outline Template

## Article Positioning

| Field | Content |
| --- | --- |
| Target article type | |
| Likely journal direction | |
| Core contribution | |
| Main evidence base | |

## Outline

### 1. Introduction

- research context
- problem statement
- significance
- article contribution

### 2. Literature Review

- concept definition
- domestic trajectory
- international trajectory
- consensus and dispute
- review conclusion

### 3. Theory Framework

- theory anchor
- concept relations
- analytical framework

### 4. Research Design

- method
- participants or materials
- data sources
- procedures
- analysis route

### 5. Findings Or Argument Development

- subsection 1
- subsection 2
- subsection 3

### 6. Discussion

- interpret findings through theory
- compare with prior studies
- explain contribution and limits

### 7. Conclusion And Implications

- main conclusion
- educational implication
- limitation
- future work

## Section Evidence Checklist

| Section | Must-have evidence |
| --- | --- |
| Introduction | |
| Literature review | |
| Theory framework | |
| Research design | |
| Findings | |
| Discussion | |

FILE:scripts/package_skill.py
#!/usr/bin/env python3
"""Package the music-education-research-writer skill as .zip, .skill, or both."""

from __future__ import annotations

import argparse
import zipfile
from pathlib import Path
from typing import Iterable, List

from validate_skill import validate_skill_root

PACKAGE_NAME = "music-education-research-writer"


def iter_package_files(root: Path) -> Iterable[Path]:
    for path in sorted(root.rglob("*")):
        if any(part in {"dist", "__pycache__"} for part in path.parts):
            continue
        if not path.is_file():
            continue
        if path.suffix == ".pyc":
            continue
        yield path


def write_archive(root: Path, output_path: Path) -> None:
    output_path.parent.mkdir(parents=True, exist_ok=True)
    with zipfile.ZipFile(output_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
        for file_path in iter_package_files(root):
            arcname = Path(root.name) / file_path.relative_to(root)
            archive.write(file_path, arcname.as_posix())


def package_skill(root: Path, output_dir: Path, fmt: str) -> List[Path]:
    ok, errors = validate_skill_root(root)
    if not ok:
        joined = "\n".join(f"- {error}" for error in errors)
        raise ValueError(f"Validation failed:\n{joined}")

    outputs: List[Path] = []

    if fmt in {"zip", "both"}:
        zip_path = output_dir / f"{PACKAGE_NAME}.zip"
        write_archive(root, zip_path)
        outputs.append(zip_path)

    if fmt in {"skill", "both"}:
        skill_path = output_dir / f"{PACKAGE_NAME}.skill"
        write_archive(root, skill_path)
        outputs.append(skill_path)

    return outputs


def main() -> int:
    parser = argparse.ArgumentParser(description="Package the skill as zip, .skill, or both.")
    parser.add_argument("path", nargs="?", default=".", help="Path to the skill root. Defaults to current directory.")
    parser.add_argument(
        "--format",
        choices=("zip", "skill", "both"),
        default="both",
        help="Archive format to generate. Defaults to both.",
    )
    parser.add_argument(
        "--output-dir",
        default="dist",
        help="Output directory for archive files. Defaults to ./dist relative to the skill root.",
    )
    args = parser.parse_args()

    root = Path(args.path).resolve()
    output_dir = Path(args.output_dir)
    if not output_dir.is_absolute():
        output_dir = root / output_dir

    try:
        outputs = package_skill(root, output_dir, args.format)
    except ValueError as exc:
        print(exc)
        return 1

    for output in outputs:
        print(f"Created archive: {output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

FILE:scripts/validate_skill.py
#!/usr/bin/env python3
"""Validate the music-education-research-writer skill package."""

from __future__ import annotations

import argparse
import re
from pathlib import Path
from typing import Dict, List, Sequence, Tuple

SKILL_NAME = "music-education-research-writer"
MAX_NAME_LENGTH = 64
MAX_DESCRIPTION_LENGTH = 1024
REQUIRED_FRONTMATTER_KEYS = ("name", "description")
REQUIRED_FILES = [
    "SKILL.md",
    "README.md",
    "references/workflow.md",
    "references/evidence_hierarchy.md",
    "references/social_science_methods.md",
    "references/music_education_ontology.md",
    "references/literature_review_principles.md",
    "references/theory_modeling_guide.md",
    "references/research_gap_taxonomy.md",
    "references/ima_integration.md",
    "templates/literature_review_template.md",
    "templates/theory_model_template.md",
    "templates/research_gap_matrix_template.md",
    "templates/opening_report_argument_template.md",
    "templates/journal_article_outline_template.md",
    "templates/classroom_practice_research_design_template.md",
    "templates/evidence_chain_table_template.md",
    "templates/literature_concept_theory_method_gap_map.md",
    "examples/example_ai_music_education_review.md",
    "examples/example_large_corpus_triage.md",
    "examples/example_theory_model.md",
    "examples/example_research_gap_matrix.md",
    "tests/sample_user_request.md",
    "tests/sample_large_corpus_request.md",
    "tests/sample_corpus_notes.md",
    "tests/expected_output_checklist.md",
    "tests/pre_publish_checklist.md",
    "scripts/validate_skill.py",
    "scripts/package_skill.py",
]

DANGEROUS_PATTERNS: Sequence[Tuple[str, str, Sequence[str]]] = [
    ("remote download command", r"\bcurl\s+(-[A-Za-z]+\s+)*https?://", (".md", ".py", ".sh", ".bash")),
    ("remote download command", r"\bwget\s+(-[A-Za-z]+\s+)*https?://", (".md", ".py", ".sh", ".bash")),
    ("python network fetch", r"requests\.(get|post|put|delete)\s*\(", (".py",)),
    ("python urllib download", r"urllib\.request\.(urlopen|urlretrieve)\s*\(", (".py",)),
    ("shell execution", r"\bos\.system\s*\(", (".py",)),
    ("shell execution", r"\bsubprocess\.(run|Popen|call|check_call|check_output)\s*\(", (".py",)),
    ("credential env access", r"\bos\.(getenv|environ)\s*\(", (".py",)),
    ("credential env access", r"\bos\.environ\[[^\]]+\]", (".py",)),
    ("secret file access", r"\.(aws|ssh)/", (".md", ".py", ".sh", ".bash")),
    ("cookie or browser store access", r"(cookies\.sqlite|Login Data|Local Storage)", (".md", ".py", ".sh", ".bash")),
]


def parse_frontmatter(content: str) -> Tuple[Dict[str, str], str]:
    match = re.match(r"^---\n(.*?)\n---\n(.*)$", content, re.DOTALL)
    if not match:
        raise ValueError("SKILL.md is missing valid YAML frontmatter.")

    raw_frontmatter = match.group(1)
    body = match.group(2)
    frontmatter: Dict[str, str] = {}

    for line in raw_frontmatter.splitlines():
        if not line.strip():
            continue
        if line.startswith(" ") or line.startswith("\t"):
            raise ValueError("Frontmatter cannot contain nested keys.")
        if ":" not in line:
            raise ValueError(f"Invalid frontmatter line: {line}")
        key, value = line.split(":", 1)
        frontmatter[key.strip()] = value.strip()

    return frontmatter, body


def validate_frontmatter(skill_md: Path, errors: List[str]) -> None:
    content = skill_md.read_text(encoding="utf-8")

    try:
        frontmatter, _body = parse_frontmatter(content)
    except ValueError as exc:
        errors.append(str(exc))
        return

    keys = tuple(frontmatter.keys())
    if keys != REQUIRED_FRONTMATTER_KEYS:
        errors.append(
            "SKILL.md frontmatter must contain only 'name' and 'description' in that order."
        )

    name = frontmatter.get("name", "")
    description = frontmatter.get("description", "")

    if not name:
        errors.append("Frontmatter is missing 'name'.")
    elif name != SKILL_NAME:
        errors.append(f"Frontmatter name must be '{SKILL_NAME}'.")
    elif not re.fullmatch(r"[a-z0-9-]+", name):
        errors.append("Frontmatter name must be kebab-case.")
    elif name.startswith("-") or name.endswith("-") or "--" in name:
        errors.append("Frontmatter name cannot start or end with '-' or contain '--'.")
    elif len(name) > MAX_NAME_LENGTH:
        errors.append(f"Frontmatter name exceeds {MAX_NAME_LENGTH} characters.")

    if not description:
        errors.append("Frontmatter is missing 'description'.")
    elif len(description) > MAX_DESCRIPTION_LENGTH:
        errors.append(f"Frontmatter description exceeds {MAX_DESCRIPTION_LENGTH} characters.")
    elif "use this skill" not in description.lower():
        errors.append("Frontmatter description must clearly say when to use the skill.")


def validate_required_files(root: Path, errors: List[str]) -> None:
    for relative_path in REQUIRED_FILES:
        path = root / relative_path
        if not path.exists():
            errors.append(f"Missing required file: {relative_path}")


def validate_required_sections(skill_md: Path, errors: List[str]) -> None:
    content = skill_md.read_text(encoding="utf-8")
    required_headings = [
        "## Skill purpose",
        "## When to use this skill",
        "## When not to use this skill",
        "## Core workflow",
        "## Token Efficiency Protocol",
        "## Evidence rules",
        "## Citation integrity rules",
        "## iMA / local corpus integration rules",
        "## Literature review procedure",
        "## Theory and model construction procedure",
        "## Research gap analysis procedure",
        "## Output templates",
        "## Safety and academic integrity constraints",
        "## Examples",
    ]

    for heading in required_headings:
        if heading not in content:
            errors.append(f"SKILL.md is missing required section: {heading}")


def validate_no_symlinks(root: Path, errors: List[str]) -> None:
    for path in root.rglob("*"):
        if path.is_symlink():
            errors.append(f"Symlink is not allowed: {path.relative_to(root)}")


def validate_dangerous_patterns(root: Path, errors: List[str]) -> None:
    for path in root.rglob("*"):
        if not path.is_file():
            continue
        if any(part in {"dist", "__pycache__"} for part in path.parts):
            continue
        if path.relative_to(root).as_posix() == "scripts/validate_skill.py":
            continue
        suffix = path.suffix.lower()
        text = path.read_text(encoding="utf-8", errors="ignore")

        for label, pattern, suffixes in DANGEROUS_PATTERNS:
            if suffix not in suffixes:
                continue
            if re.search(pattern, text, re.IGNORECASE):
                errors.append(f"Dangerous pattern detected in {path.relative_to(root)}: {label}")


def validate_no_placeholder_todos(root: Path, errors: List[str]) -> None:
    for path in root.rglob("*.md"):
        if any(part in {"dist", "__pycache__"} for part in path.parts):
            continue
        text = path.read_text(encoding="utf-8", errors="ignore")
        if "[TODO" in text or "TODO:" in text:
            errors.append(f"Placeholder TODO found in {path.relative_to(root)}")


def validate_skill_root(root: Path) -> Tuple[bool, List[str]]:
    errors: List[str] = []

    if not root.exists():
        return False, [f"Path does not exist: {root}"]
    if not root.is_dir():
        return False, [f"Path is not a directory: {root}"]

    validate_required_files(root, errors)

    skill_md = root / "SKILL.md"
    if skill_md.exists():
        validate_frontmatter(skill_md, errors)
        validate_required_sections(skill_md, errors)

    validate_no_symlinks(root, errors)
    validate_dangerous_patterns(root, errors)
    validate_no_placeholder_todos(root, errors)

    return not errors, errors


def main() -> int:
    parser = argparse.ArgumentParser(description="Validate the music-education-research-writer package.")
    parser.add_argument("path", nargs="?", default=".", help="Path to the skill root. Defaults to current directory.")
    args = parser.parse_args()

    root = Path(args.path).resolve()
    ok, errors = validate_skill_root(root)

    if ok:
        print("Skill package is valid.")
        return 0

    print("Skill package validation failed:")
    for item in errors:
        print(f"- {item}")
    return 1


if __name__ == "__main__":
    raise SystemExit(main())

FILE:examples/example_theory_model.md
# Example: Theory Model For Human-AI Collaborative Music Creation

> This example is based on placeholder source IDs from a sample corpus and is intended to show output shape rather than final scholarly claims.

## Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | theory and model construction |
| Output mode | Standard Mode |
| Materials sufficient | partially |
| Most relevant theory sources | A01, A02, B01, D01 |
| Whether deeper expansion is worth doing now | yes, after the main model is stabilized |

## 1. Modeling Premise

| Field | Working content |
| --- | --- |
| Topic | Human-AI collaborative music creation in ordinary high-school music classes |
| Research object | Students participating in guided composition activities |
| Setting | Selective compulsory or creation-oriented music module |
| Main problem | How AI-assisted co-creation influences participation, motivation, and creative output quality |
| Candidate theory base | self-determination theory, sociocultural theory, creativity theory |
| Preferred method | design-based research plus classroom observation and artifact analysis |

## 2. Concept Model

### 2.1 Core Concepts

| Concept | Definition | Source basis | Notes |
| --- | --- | --- | --- |
| Human-AI co-creation | Students use AI tools to generate and revise musical ideas under pedagogical guidance | A01, A02 | classroom mediation is part of the concept |
| Creative engagement | sustained participation in ideation, revision, and reflection | B01, D01 | includes emotional and behavioral involvement |
| Creative output quality | originality, coherence, and expressive fit of student works | A03, C01 | needs explicit rubric |
| Creative agency | perceived authorship and control in the co-creation process | A02, D02 | useful for controversy analysis |

### 2.2 Concept Relations

| Relation | Explanation | Theory basis | Confidence |
| --- | --- | --- | --- |
| human-AI co-creation -> creative engagement | lowered entry barrier and richer idea prompts may increase participation | self-determination | medium |
| teacher mediation -> creative agency | guided revision helps students retain ownership | sociocultural theory | medium |
| creative engagement -> output quality | deeper revision and reflection can improve student works | creativity theory | medium |
| tool dependence -| creative agency | overreliance may weaken authorship perception | creativity theory | low to medium |

### 2.3 Concept Model Summary

The concept model treats AI not as an isolated causal force but as a mediating tool whose educational value depends on teacher scaffolding, student engagement, and revision practices. Creative agency is the key balancing concept because it links technological affordance with educational quality.

## 3. Analytical Framework Model

| Element | Content |
| --- | --- |
| Research question | How does guided human-AI collaborative composition shape student engagement, creative agency, and creative output quality in high-school music classes? |
| Independent or focal variable | guided human-AI collaborative composition task |
| Dependent or focal outcome | engagement, agency, output quality |
| Mediator or process path | revision depth, peer discussion, teacher feedback |
| Moderator or condition | prior musical experience, tool familiarity, lesson design |
| Observable indicators | participation frequency, revision logs, reflective statements, rubric scores |
| Data sources | observation notes, student works, interviews, teacher logs, rubrics |
| Analysis route | classroom process coding plus artifact analysis plus reflective interview interpretation |

### Analytical Framework Narrative

This framework is suitable when the study aims to explain not only whether AI tools are useful, but how classroom mediation changes their educational meaning. It works especially well in design-based research or action research settings where teaching design is part of the analytic object.

## 4. Paper-Writing Model

| Section | Function | Expected material |
| --- | --- | --- |
| Problem entry | explain why AI music generation is educationally relevant but theoretically unstable | policy notes, curriculum needs, field debates |
| Literature base | review AI music education, creativity, and classroom technology studies | A and B literature |
| Theory anchor | connect self-determination, sociocultural mediation, and creativity | theory synthesis |
| Method route | present classroom intervention and evidence collection | DBR or action research design |
| Core analysis | show process, products, and participant meaning | observations, artifacts, interviews |
| Discussion | interpret mechanism, risks, and pedagogical implications | theory plus field evidence |
| Implication | propose classroom framework and future research path | practice conversion |

## 5. Model Evaluation

| Model type | Suitable research question | Usable data | Risks | Publication direction |
| --- | --- | --- | --- | --- |
| Concept model | what concepts organize the topic | literature, field notes | may stay abstract | theoretical or review article |
| Analytical framework | how to operationalize the topic in research | observations, artifacts, interviews | data collection burden | empirical education article |
| Paper-writing model | how to structure the argument | full corpus | may overfit one target journal | opening report or article outline |

## Expansion Recommendation

The highest-value next step is to expand the analytical framework model first. The concept model is stable enough for current use, while the paper-writing model can remain at outline level until the user confirms target journal direction.

FILE:examples/example_ai_music_education_review.md
# Example: AI Music Education Literature Review

> This example is a format demonstration built from placeholder source IDs such as `A01`, `B01`, and `D01`. It does not claim that those IDs are complete public bibliographic records. Replace them with verified sources before publication.

## Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | literature review plus topic framing |
| Output mode | Standard Mode |
| Materials sufficient | partially |
| Priority literature clusters | concept definition, domestic curriculum studies, international co-creation theory, classroom process evidence |
| Whether expansion is worth doing now | yes, but only after screening high-relevance materials |

## Corpus Triage

| Relevance bucket | Material IDs | Handling rule |
| --- | --- | --- |
| High relevance | A01, A02, B01, B02, D01 | analyze first |
| Medium relevance | A03, C01, D02 | summarize briefly |
| Low relevance | D03 | keep in reserve |
| 待核验 | A03, C01, D03 | verify before relying on them strongly |

## Review Structure Table

| Section | Focus | Key source IDs | Notes |
| --- | --- | --- | --- |
| Concept definition | AI-assisted music creation in high-school music education | A01, B01 | clarify difference between tool use and pedagogy |
| Domestic trajectory | curriculum, classroom experimentation, and technology integration in China | B01, B02, D01 | domestic studies emphasize curricular feasibility |
| International trajectory | creativity, human-AI collaboration, and technology acceptance | A02, A03, C01 | more attention to co-creation theory |
| Theory lenses | self-determination, sociocultural mediation, creativity theory | A02, A03 | theory integration remains partial |
| Methods used | literature review, case description, questionnaire, pilot teaching | B02, C01, D01 | classroom observation remains thin |
| Consensus | AI tools can increase interest and idea generation under guided use | A02, B02, D01 | guidance quality matters |
| Controversies | authorship, over-reliance, and assessment validity | A03, C01 | mixed findings on creativity depth |
| Limitations | lack of stable classroom frameworks in Chinese high schools | B01, D01 | strong entry point for further research |
| Topic implication | design a classroom-based human-AI co-creation study | A02, B02, D01 | suitable for DBR or action research |

## Core Theme Clusters And Key Judgments

### Cluster 1. Concept Definition

- `AI-assisted music creation` is better framed as a pedagogically mediated co-creation process than as simple tool use `[A01][B01]`.
- Teacher guidance is part of the construct, not merely a background condition `[A01][B01]`.
- This cluster is worth expanding first if the user is preparing a formal literature review section.

Representative evidence:

- A01
- B01

### Cluster 2. Domestic Curriculum And Classroom Fit

- Domestic materials emphasize curriculum fit and core competencies more than detailed mechanism analysis `[B01][B02]`.
- Existing domestic writing often discusses feasibility but provides thin classroom process evidence `[B02][D01]`.
- This cluster is high value for Chinese core-journal framing.

Representative evidence:

- B01
- B02
- D01

### Cluster 3. International Human-AI Co-Creation Theory

- International literature provides stronger vocabulary around agency, creativity, and authorship `[A02][A03]`.
- Transfer to Chinese high-school music classrooms remains incomplete because contexts differ.
- This cluster supports theory building more than direct classroom prescription.

Representative evidence:

- A02
- A03
- C01

### Cluster 4. Method And Evidence Gap

- Existing materials rely too much on conceptual discussion and pilot descriptions `[B02][C01]`.
- Classroom observation, artifact analysis, and DBR remain relatively weak.
- This cluster strongly supports a method-gap argument.

Representative evidence:

- B02
- C01
- D01

### Cluster 5. Practice Conversion And Risk

- AI tools may improve entry into composition, but authorship and overreliance remain active concerns `[A03][D02]`.
- A publishable study should convert abstract claims into classroom-process evidence and observable indicators.
- This cluster is worth expanding only after the user confirms a practice-oriented or empirical direction.

Representative evidence:

- A03
- D02

## Expansion Recommendation

This corpus is worth expanding, but the best next step is not a full long-form review. The highest-value expansion path is:

1. expand Cluster 2 for Chinese curriculum fit
2. expand Cluster 3 for theory anchor
3. expand Cluster 4 for method-gap justification

## Expandable Review Draft

The following draft is a Phase 2 example rather than the default first response.

### 1. Concept Definition

Current materials suggest that `AI-assisted music creation` should not be defined merely as the use of generative tools in music class. A more useful definition treats it as a pedagogically mediated co-creation process in which students use AI tools to generate, revise, evaluate, and reflect on musical ideas within curricular goals `[A01][B01]`. This distinction matters because tool availability alone does not explain learning outcomes; classroom design and teacher mediation are part of the concept itself.

### 2. Domestic Research Trajectory

The domestic path represented in the sample corpus pays strong attention to curriculum fit, classroom feasibility, and the language of core musical competencies `[B01][B02]`. These sources tend to discuss how AI tools can support interest, composition entry, and participation, but they less often provide sustained process evidence from ordinary high-school classrooms. Practice notes and exported teaching reflections `[D01]` enrich the scene description, yet they still need academic triangulation.

### 3. International Research Trajectory

International materials in the sample corpus more often frame AI-supported music work through creativity, co-creation, or human-tool mediation `[A02][A03]`. They provide useful conceptual resources for discussing agency, revision, and authorship, but these findings do not automatically transfer into the Chinese high-school curriculum context. The main transfer problem is that many studies focus on exploratory creative settings rather than curriculum-constrained classroom teaching.

### 4. Main Theory Lenses

Three theory lenses stand out in the sample corpus. Self-determination theory helps explain changes in motivation and perceived competence. Sociocultural theory clarifies how tools, peers, and teacher guidance mediate musical creation. Creativity theory helps analyze originality, revision, and expressive development `[A02][A03]`. However, the corpus does not yet show a stable framework that integrates all three for high-school music classes.

### 5. Main Methods Used

The sample literature relies mainly on conceptual discussion, pilot classroom descriptions, and self-report evidence `[B02][C01]`. Classroom observation, student artifact analysis, and iterative design-based research are comparatively weak. This suggests a method gap: the field needs richer process evidence to explain how AI-supported creation unfolds in real lessons.

### 6. Consensus

Across source classes, a provisional consensus appears: AI tools can lower the entry threshold for composition tasks, increase participation, and expand idea generation when teacher guidance remains explicit `[A02][B02][D01]`. This is a useful but still qualified conclusion because the underlying evidence is uneven across contexts.

### 7. Controversies

The main controversies concern authorship, dependence on generated material, and the validity of evaluating creativity in AI-supported work `[A03][C01]`. Some materials treat AI as an enhancer of creative confidence, while others warn that creative ownership may become blurred if students rely on the tool without reflective revision.

### 8. Research Limitations

The sample corpus reveals four concrete limitations: limited evidence from ordinary high-school music classrooms, weak integration between creativity theory and music-education theory, insufficient process data, and few classroom-ready teaching frameworks for human-AI co-creation `[B01][B02][D01]`.

### 9. Implications For The Topic

For a user interested in `human-AI collaborative music creation in high-school music classes`, the most promising path is not a generic technology narrative but a classroom-based study of how AI-mediated creation affects participation, aesthetic judgment, and revision quality under guided teaching conditions. This direction is suitable for action research or design-based research.

## Citation And Evidence List

| Claim or subsection | Source IDs | Evidence class | Verification | Note |
| --- | --- | --- | --- | --- |
| concept definition | A01, B01 | A, B | 部分核验 | replace with verified bibliographic entries |
| domestic trajectory | B01, B02, D01 | B, D | 部分核验 | D01 is contextual only |
| international trajectory | A02, A03, C01 | A, C | 待核验 | confirm publication metadata |
| consensus | A02, B02, D01 | A, B, D | 部分核验 | keep D as practice echo, not proof |

FILE:examples/example_large_corpus_triage.md
# Example: Large Corpus Triage

> This example shows the default behavior when the user provides a large mixed corpus. The first response should screen and prioritize rather than deeply summarize every source.

## Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | corpus triage before literature review and model building |
| Output mode | Standard Mode |
| Materials sufficient | partially sufficient |
| Most likely output now | material screening, priority clusters, and next-step recommendation |
| Need to expand now | not yet |

## Corpus Overview

| Material type | Estimated volume | Immediate action |
| --- | --- | --- |
| peer-reviewed articles and dissertations | high | screen for direct topic fit first |
| policy and curriculum files | medium | prioritize documents directly tied to high-school music curriculum |
| classroom observations and logs | medium | prioritize recent and well-annotated records |
| questionnaire and interview materials | medium | reserve for later method design unless directly needed now |
| WeChat and public articles | high | keep as contextual background only |

## Relevance Screening

| Bucket | Typical content | Handling rule |
| --- | --- | --- |
| High relevance | AI music education, high-school music curriculum, human-AI co-creation, classroom mechanism | deep analysis first |
| Medium relevance | broader educational technology, general creativity studies, adjacent music pedagogy | brief summary only |
| Low relevance | generic AI background, unrelated arts-tech commentary, broad music history | defer |
| 待核验 | unclear source metadata, unverified reports, public article exports | verify before heavy use |

## Priority Clusters

| Priority | Cluster | Why it matters now |
| --- | --- | --- |
| 1 | Chinese high-school music curriculum and core competencies | anchors the China-context framing |
| 2 | human-AI co-creation theory and learner agency | anchors theory and concept definition |
| 3 | classroom observation and student work evidence | anchors feasible empirical design |
| 4 | domestic classroom technology integration studies | anchors method and publication fit |
| 5 | policy and curriculum standards | anchors problem significance and contextual legitimacy |

## Deferred Materials

- general AI industry commentary
- low-relevance music technology news
- repeated public articles with overlapping claims
- materials without stable metadata

## Recommended Next Step

Do not expand the entire corpus. The best next step is to analyze one of these first:

- Cluster 1 for problem framing
- Cluster 2 for theory model building
- Cluster 3 for method and evidence design

FILE:examples/example_research_gap_matrix.md
# Example: Research Gap Matrix

> This matrix uses sample source IDs only. Replace all IDs with verified records before publication or formal proposal submission.

## Phase 1 Quick Diagnosis

| Item | Short answer |
| --- | --- |
| Task type | research gap analysis |
| Output mode | Standard Mode |
| Materials sufficient | partially |
| Priority sources | B01, B02, A02, D01 |
| Whether gap analysis is reliable now | reliable for preliminary prioritization, but some items still need verification |

| Gap type | Evidence basis | Concrete gap statement | Candidate research question | Feasible method | Expected data | Publication potential | Risk level |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Object gap | B01, B02 | Existing discussion rarely focuses on ordinary high-school students in non-elite school settings. | How do ordinary high-school students engage with AI-supported music creation tasks? | case study, survey, mixed methods | questionnaire, interviews, class artifacts | medium to high | medium |
| Scene gap | D01, D02, B02 | Real classroom co-creation scenes are described thinly; many texts stay at a conceptual level. | What classroom interaction patterns emerge during human-AI collaborative composition lessons? | classroom observation, action research | observation notes, video, teacher log | high | medium |
| Method gap | B02, C01 | The topic relies heavily on conceptual discussion and pilot description, with limited DBR or iterative classroom studies. | What new insight emerges from a DBR approach to AI-assisted composition teaching? | DBR | iterative lesson records, student works, reflection logs | high | medium |
| Theory gap | A02, A03 | Creativity theory, music education theory, and technology acceptance are seldom integrated. | How can creativity theory and sociocultural mediation jointly explain student agency in AI-assisted composition? | literature review, conceptual modeling | verified literature corpus | medium | low |
| Data gap | C01, D01 | Process data and artifact-based evidence remain weak. | How do revision traces and student works change during AI-supported composition? | artifact analysis, observation | drafts, prompts, final works, revision notes | high | medium |
| Practice gap | B01, D02 | Abstract claims about AI use rarely become implementable lesson sequences. | How can a high-school music composition unit be redesigned into a practical human-AI co-creation module? | curriculum-development research, DBR | teaching plan, trial feedback, student outputs | high | medium |
| China-context gap | A02, B01 | International findings do not directly explain Chinese curriculum standards and classroom routines. | How should foreign human-AI co-creation findings be adapted to Chinese high-school music curricula? | literature review plus local case study | literature, policy, local teaching records | medium to high | low to medium |
| Cross-disciplinary gap | A03, C01 | AI music generation research and music education research still lack a stable shared analytic framework. | What analytical framework can connect AI music generation and music education in a coherent way? | conceptual paper, review | verified literature corpus | medium | low |

## Priority Selection

| Priority | Recommended question | Why it is promising | Main condition to satisfy |
| --- | --- | --- | --- |
| 1 | What classroom interaction patterns emerge during human-AI collaborative composition lessons? | strong novelty, strong classroom relevance, data can be locally collected | observation and artifact data must be accessible |
| 2 | What new insight emerges from a DBR approach to AI-assisted composition teaching? | good fit for practice innovation and publishable method contribution | requires iterative lesson implementation |
| 3 | How should foreign human-AI co-creation findings be adapted to Chinese high-school music curricula? | strong contextual contribution with manageable scope | needs verified domestic and international literature |

## Final Recommendation

The most balanced entry point is the `scene gap` plus `method gap` combination: a classroom-based design or action study can generate process evidence, practice value, and a clearer argument than a purely conceptual discussion.

## Expansion Recommendation

Do not expand all gaps at once. The best next step is to deepen the `scene gap`, `method gap`, and `China-context gap` combination first.

FILE:tests/sample_large_corpus_request.md
# Sample Large Corpus Request

我准备了一个比较大的研究资料库，里面大概有：

- 40 篇中文教育或音乐教育论文
- 12 篇英文 AI music / music technology / education 相关文章
- 8 份课程标准、政策文件或教研材料
- 15 份课堂观察记录
- 6 份学生问卷与访谈整理
- 20 多篇微信公众号和行业文章摘录
- 一些我自己在 iMA 里的读书笔记和研究日志导出

主题仍然是“AI辅助高中音乐创作教学中的人机协作机制”。

请先不要直接写成长文，也不要把所有材料都总结一遍。先帮我：

1. 判断当前任务属于哪一类；
2. 判断这些材料是否足够支撑研究；
3. 先筛选高相关、中相关、低相关、待核验材料；
4. 告诉我最值得优先处理的 3—5 个材料簇；
5. 再建议下一步是做文献综述、理论模型还是研究空白矩阵。

请用 Standard Mode。

FILE:tests/sample_corpus_notes.md
# Sample Corpus Notes

## Source Inventory

| Source ID | Type | Class | Verification | Short note |
| --- | --- | --- | --- | --- |
| A01 | verified journal article | A | 已核验 | discusses AI-assisted composition and creativity support |
| A02 | verified international journal article | A | 部分核验 | focuses on human-AI co-creation and learner agency |
| A03 | verified journal article or dissertation | A | 待核验 | covers authorship or creativity evaluation |
| B01 | CSSCI or core-journal article | B | 已核验 | connects music curriculum with creative competencies |
| B02 | Chinese education journal article | B | 部分核验 | classroom technology integration in music education |
| C01 | conference or institutional report | C | 待核验 | trend report on AI-assisted arts education |
| D01 | classroom observation record | D | 已核验 | notes on student engagement and revision behavior |
| D02 | teacher reflection or meeting note | D | 已核验 | notes on teaching flow and tool-use concerns |
| D03 | exported public article excerpt | D | 待核验 | public discussion of AI music tool use |
| E01 | user intuition memo | E | 已核验 | preliminary research idea and concern |

## Topic Notes

- topic focus: human-AI collaborative music creation
- school context: ordinary high-school music class
- likely interest: classroom mechanism, engagement, creative output, curriculum feasibility
- likely method candidates: action research, DBR, observation plus artifact analysis, mixed methods

## Default Triage Hint

- high relevance: A01, A02, B01, B02, D01
- medium relevance: A03, C01, D02
- low relevance: D03, E01
- wait for verification: A03, C01, D03

FILE:tests/sample_user_request.md
# Sample User Request

我想写一篇偏教育研究方向、目标尽量靠近中文核心期刊的论文，主题是“AI辅助高中音乐创作教学中的人机协作机制”。我现在手里有一批资料：

- 几篇中文核心或教育类期刊论文
- 两篇国外关于 AI music co-creation 的英文文章
- 我自己两次课堂试教后的观察记录
- 一份学生学习反馈问卷
- 一些从 iMA 导出的 Markdown 笔记和公众号文章摘录

请不要直接代写整篇论文。先帮我做三件事：

1. 建立文献综述结构
2. 提炼可用的理论模型
3. 识别研究空白，并给出最值得做的 3 个研究问题

要求：

- 区分证据等级
- 不要伪造文献
- 尽量贴近中国普通高中音乐课堂
- 输出用 Markdown
- 如果材料还不够，请列出“需要补充的文献清单”

FILE:tests/expected_output_checklist.md
# Expected Output Checklist

Use this checklist to evaluate whether the skill output matches the package design.

## Required

- The response identifies the user's immediate task instead of jumping into full-paper drafting.
- The response chooses or implies an output mode: Brief, Standard, or Deep.
- The response defaults to Standard Mode unless the user explicitly asks otherwise.
- If the user asks for a full paper, the response first suggests staged writing: review, theory, method, data, discussion.
- The response follows the default order: judge, triage, frame, expand locally, write prose last.
- The response builds a research frame with object, setting, concepts, theory, method tendency, and publication direction.
- The response inventories or references available materials.
- When the corpus is large, the response screens materials before deep analysis.
- When the corpus is large, the response separates high, medium, low, and `待核验` materials.
- The response prioritizes 3 to 5 key material clusters instead of summarizing everything.
- The response classifies evidence by `A` to `E`.
- The response marks uncertain material `待核验`.
- The response does not fabricate authors, years, journals, DOI values, or policy documents.
- The literature review is organized by concept, trajectory, theory, method, consensus, controversy, limitation, and implication.
- Default literature-review output stays at structure plus key theme clusters unless the user explicitly asks for deep expansion.
- The response outputs at least three model views when theory modeling is requested.
- Default theory-model output starts with one main model and 1 to 2 backup models rather than an exhaustive theory history.
- The research gap section uses specific gap types instead of vague `research is insufficient` language.
- Default research-gap output focuses on 5 to 8 highest-value gaps rather than a long undifferentiated list.
- If materials are insufficient, the response outputs `需要补充的文献清单`.
- The final output remains in Markdown.

## Strong Signals

- The response distinguishes domestic and international research trajectories.
- The response maps literature to concepts, theories, methods, and gaps.
- The response suggests suitable social-science methods rather than defaulting to generic empirical claims.
- The response stays close to music education and Chinese high-school classroom language.
- The response does not treat classroom notes or public articles as peer-reviewed evidence.
- The response emphasizes problem consciousness, theoretical contribution, method rigor, and Chinese education context for core-journal writing.
- Paragraph-level drafting shows what evidence the paragraph is based on.
- The response uses tables, matrices, or checklists when those are more efficient than long prose.
- The response clearly says `材料不足` when evidence is weak instead of filling with generic language.

## Failure Signals

- fabricated references or unverifiable citation details
- generic STEM-style discussion detached from music education
- author-by-author literature list without synthesis
- direct full-paper generation despite limited evidence
- no research gap matrix or no evidence chain
- polished academic-sounding prose that hides insufficient evidence
- exhaustive summary of every material despite a large corpus
- long prose before corpus triage in a large-material scenario

FILE:tests/pre_publish_checklist.md
# Pre-Publish Checklist

Use this checklist before uploading the package to SkillHub or ClawHub.

## Package identity

- Folder name is exactly `music-education-research-writer`
- `SKILL.md` exists in the root
- `SKILL.md` frontmatter contains only `name` and `description`
- `name` is exactly `music-education-research-writer`
- `description` clearly explains when to use the skill

## Content integrity

- `SKILL.md` contains all required sections
- `SKILL.md` contains `Token Efficiency Protocol`
- references files are complete
- templates files are complete
- example files are complete
- test files are complete
- no placeholder TODO text remains

## Academic integrity

- no fabricated authors
- no fabricated years
- no fabricated journals
- no fabricated DOI values
- no fabricated policy documents
- no paragraphs that hide weak evidence with vague academic language
- evidence classes `A` to `E` are clearly described
- `需要补充的文献清单` is supported for low-evidence cases
- large-corpus scenarios are handled by screening before deep analysis

## Safety

- no symlinks exist in the package
- no remote download logic exists
- no hidden credential-reading logic exists
- no automatic shell execution logic exists
- no full-disk scanning logic exists
- no automatic upload logic exists
- no token-wasting default behavior is implied by the examples or templates

## Packaging

- `python3 scripts/validate_skill.py .` passes
- `python3 scripts/package_skill.py . --format zip` passes
- `python3 scripts/package_skill.py . --format skill` passes
- `dist/music-education-research-writer.zip` exists
- `dist/music-education-research-writer.skill` exists
- opening either archive shows the root directory `music-education-research-writer/`

## Hub submission

- README is readable by humans
- SKILL description is short enough for hub listings
- examples are realistic
- token-efficiency behavior is visible in SKILL, README, examples, and tests
- package does not overclaim APIs or integrations
- upload notes state that the skill relies on user-provided corpora

FILE:references/music_education_ontology.md
# Music Education Ontology

## Purpose

This ontology gives the skill a domain-specific vocabulary so it can reason inside music education rather than treating the topic as generic academic writing.

## Core Topic Clusters

### Curriculum And Schooling

- high-school music curriculum
- selective compulsory modules
- ordinary high-school music classroom
- school-based curriculum
- interdisciplinary arts curriculum
- music and drama

### Core Competencies And Learning Outcomes

- music aesthetics
- aesthetic judgment
- music performance
- music creation
- cultural understanding
- core musical competencies
- creative confidence
- learning motivation
- classroom participation

### Teaching And Learning Processes

- listening guidance
- appreciation teaching
- composition pedagogy
- improvisation
- peer collaboration
- reflection and revision
- formative assessment
- project-based learning

### Technology And AI

- AI music creation
- human-AI collaborative composition
- AIGC music tools
- Suno
- Mureka
- multimodal creative workflow
- tool acceptance
- ethical use of generative AI

### Culture And Context

- national music culture
- local music culture
- regional music culture
- place-based music education
- folk music inheritance
- community-linked curriculum

## Construct Suggestions

| Topic | Possible constructs or variables |
| --- | --- |
| Music aesthetics | perception, judgment, response depth, reflective articulation |
| Music creation | originality, structure, revision quality, expressive coherence |
| Classroom engagement | behavioral participation, emotional investment, sustained attention |
| Motivation | intrinsic motivation, perceived competence, task value, autonomy |
| Human-AI collaboration | tool acceptance, co-creation strategy, authorship perception, creative agency |
| Cultural understanding | contextual knowledge, interpretive depth, identity linkage |

## Common Theory Lenses

| Theory lens | Useful for |
| --- | --- |
| aesthetic education | music appreciation, aesthetic judgment, value of listening and response |
| constructivism | learner-centered creation, reflection, knowledge building |
| sociocultural theory | collaboration, mediation, classroom interaction, cultural tools |
| creativity theory | composition, originality, divergent production, revision process |
| self-determination theory | motivation, autonomy, competence, relatedness |
| technology acceptance or technology integration models | AI tool adoption, teacher and student acceptance |
| activity theory | human-tool-community interaction in classroom tasks |
| curriculum theory | module design, curriculum alignment, standards interpretation |

## Scene Vocabulary

Use scene-aware language when building questions or models:

- music appreciation class
- composition workshop
- selective compulsory module
- performance and creation integrated class
- AI-assisted composition task
- local music culture unit
- classroom demonstration and critique session

## Observable Indicators

| Dimension | Example indicators |
| --- | --- |
| participation | turn-taking, contribution frequency, completion rate |
| aesthetic response | interpretive detail, comparative listening quality, verbal articulation |
| creative outcome | originality, thematic development, structural coherence |
| human-AI interaction | prompt strategy, revision depth, tool dependency, authorship stance |
| cultural understanding | use of contextual references, style awareness, cultural explanation |

## China-Context Reminders

- Distinguish curriculum-language from imported theory-language.
- Note when foreign theories need adaptation to ordinary high-school music classrooms in China.
- Treat local music culture as a curricular and cultural resource, not only as background decoration.
- When relevant, align concepts with curriculum standards, core competencies, and actual school implementation conditions.

FILE:references/workflow.md
# Workflow

## Purpose

This workflow helps the skill support early-stage academic reasoning for social-science and music-education research without collapsing into one-shot paper generation.

The default behavior is:

1. judge first
2. triage second
3. frame the problem third
4. expand only the highest-value part
5. write formal prose last

## Step 1. Diagnose The Research Task

Identify which of these tasks the user actually needs:

1. Literature review
2. Theory or concept model construction
3. Research gap identification
4. A combined package of the three
5. Topic incubation
6. Opening-report pre-argumentation
7. Core-journal article framing

If the user asks for a complete paper immediately, do not jump straight into full-paper drafting. First recommend a staged path:

1. literature review
2. theory and concept framework
3. method design
4. data and evidence
5. analysis and discussion

### Minimal Clarification Rule

If the request is underspecified, ask the smallest useful question set. Typical missing fields are:

- topic
- population
- classroom or institutional setting
- target journal or degree context
- available corpus
- preferred method

If a usable corpus is already supplied, do not block on extra questioning.

## Step 2. Build The Research Frame

Extract and restate:

- research object
- research scene
- central concepts or variables
- theory background
- disciplinary home
- method tendency
- likely publication direction
- most suitable paper type

### Output Pattern

Use a short structure table before producing paragraphs:

| Field | Working interpretation |
| --- | --- |
| Research object | |
| Setting | |
| Core concepts or variables | |
| Theory background | |
| Method tendency | |
| Publishable direction | |
| Suitable paper type | |

## Step 3. Triage Corpus Before Deep Reading

When the corpus is large, start with:

- corpus overview
- material categories
- high-relevance materials
- medium-relevance materials
- low-relevance materials
- `待核验` materials
- recommended 3 to 5 priority clusters

Do not deeply analyze all materials at once.

## Step 4. Read Sources And Rank Evidence

Inventory all available material first. Distinguish:

- academic literature
- policy or standards
- classroom data
- personal notes
- media or public writing

Then assign evidence classes according to `references/evidence_hierarchy.md`.

### Source Handling Rules

- Preserve file names, page references, paragraph markers, or note IDs when possible.
- If a source cannot be opened or verified, mark it `待核验`.
- Do not infer journal status or peer-review status from tone alone.
- If the corpus is too thin for a stable synthesis, prepare `需要补充的文献清单`.

## Step 5. Choose Token Budget Mode

Default to `Standard Mode`.

- `Brief Mode`: 300 to 800 words, tables first, quick judgment only
- `Standard Mode`: 1000 to 2500 words, structured analysis, no full prose by default
- `Deep Mode`: 3000 plus words only when explicitly requested

## Step 6. Generate The Literature Review

The review should be organized by:

- concept definition
- domestic research trajectory
- international research trajectory
- theory lenses
- methods used
- consensus
- controversy
- limitations
- implications for the user's topic

Use `references/literature_review_principles.md` and `templates/literature_review_template.md`.

## Step 7. Construct Theory And Analysis Models

The skill should produce at least three linked model views:

1. Concept model
2. Analytical framework model
3. Paper-writing model

Each model must include:

- suitable research problem
- theory basis
- concept or variable relations
- observable indicators or usable data
- likely risks
- suitable publication direction

Use `references/theory_modeling_guide.md` and `templates/theory_model_template.md`.

## Step 8. Identify Research Gaps

Gap analysis must be concrete rather than formulaic. Check for:

- object gaps
- scene gaps
- method gaps
- theory gaps
- data gaps
- practice-transfer gaps
- China-context gaps
- interdisciplinary gaps

Use `references/research_gap_taxonomy.md` and `templates/research_gap_matrix_template.md`.

## Step 9. End With Actionable Next Steps

Every substantial output should end with:

- most promising research question candidates
- missing evidence
- `需要补充的文献清单` when needed
- validation risks
- next retrieval step
- next writing step

## Quality Gates

Before finalizing, confirm that the output:

- starts with the smallest useful decision-support output
- does not waste tokens on low-value background
- does not fabricate citations
- separates evidence classes clearly
- uses social-science method language where appropriate
- fits music-education or education research vocabulary
- links literature to concepts, theories, methods, and gaps
- is usable in Markdown for Word, WPS, Obsidian, Notion, or iMA notes

FILE:references/social_science_methods.md
# Social Science Methods

## Purpose

This guide helps the skill suggest methods that fit the research question, the available data, and the publication context instead of defaulting to generic empirical language.

## Method Selection Table

| Method | Suitable questions | Common data | Strengths | Main risks |
| --- | --- | --- | --- | --- |
| Literature research | What has been studied, debated, or omitted in a field | articles, books, policies, reviews | strong for concept definition and field mapping | may become descriptive if not problem-oriented |
| Case study | How or why a bounded case works in context | school cases, teacher cases, curriculum cases, student works | rich contextual explanation | limited transferability if case logic is weak |
| Action research | How practice changes through iterative intervention | teaching plans, reflections, observations, student feedback | strong practice linkage | researcher role may bias interpretation |
| Design-based research | How to design, test, and refine an intervention in real settings | prototype lessons, classroom iterations, artifacts, reflections | good for innovation and course design | needs a clear iteration logic |
| Classroom observation | What happens in real teaching and learning processes | observation notes, video, coding sheets, field notes | good for process evidence | requires explicit observation dimensions |
| Mixed methods | How trends and mechanisms combine | questionnaires plus interviews, scores plus observations | balances breadth and depth | integration may be superficial if design is loose |
| Questionnaire survey | What patterns, attitudes, or self-reports appear across a group | survey responses, scale scores | efficient for broad tendencies | weak if constructs and sampling are not rigorous |
| Interview study | How participants interpret experiences or practices | transcripts, recordings, interview notes | deep on meaning and perception | needs careful sampling and coding discipline |
| Content analysis | What themes, categories, or patterns appear in texts or artifacts | policy texts, syllabi, student works, public discourse | useful for curricular and discourse analysis | coding rules must be explicit |
| Preliminary grounded-theory coding | What categories and relationships emerge from field material | interviews, logs, observations, reflections | strong for exploratory category building | easy to overclaim theory from thin data |
| Curriculum-development research | How a curriculum or module can be structured and justified | standards, teaching plans, trials, feedback | strong for school-based curriculum work | may lack outcome evidence if evaluation is weak |
| Experiment or quasi-experiment | Whether an intervention influences a measurable outcome | pre-post scores, control comparison, rubrics | clearer causal language | design and measurement quality are critical |

## Method Prompts By Topic

| Topic tendency | Strong candidate methods |
| --- | --- |
| Literature synthesis or theoretical positioning | literature research, content analysis |
| Real classroom innovation | action research, design-based research, classroom observation |
| Student perception, motivation, or engagement | questionnaire survey, interview study, mixed methods |
| Music creation quality or product comparison | content analysis, rubrics, quasi-experiment, mixed methods |
| Policy or curriculum interpretation | literature research, content analysis, case study |
| Local or regional music culture integration | case study, curriculum-development research, interview study, classroom observation |

## Data Alignment Questions

Before recommending a method, answer:

1. What is the main question: description, explanation, evaluation, intervention, or design?
2. What data already exists?
3. What data can realistically be collected?
4. Does the study need classroom process evidence, learner outcome evidence, or both?
5. Is the paper aiming for theory contribution, practice contribution, or both?

## Publication Alignment Notes

| Publication direction | Method notes |
| --- | --- |
| Literature review or theoretical article | strong synthesis logic matters more than large datasets |
| Core-journal empirical article | method fit, variable definition, and data credibility are essential |
| Practice-oriented education journal | classroom design, implementation detail, and reflective evidence matter |
| Opening report | feasibility and method coherence matter more than polished prose |

## Safe Language For Method Claims

- Use `suggests`, `indicates`, `is consistent with`, or `can be interpreted as` when causality is weak.
- Reserve strong causal claims for appropriately designed experiments or quasi-experiments.
- If data is exploratory, say so explicitly.

FILE:references/theory_modeling_guide.md
# Theory Modeling Guide

## Goal

This guide helps the skill turn scattered literature and field materials into explicit concept and theory structures that can support a paper, an opening report, or a classroom-practice study.

## Minimum Modeling Outputs

Produce at least three models when the corpus allows:

1. Concept model
2. Analytical framework model
3. Paper-writing model

## Model 1. Concept Model

### Purpose

Show the key concepts and their direct relationships.

### Include

- core concepts
- subordinate dimensions
- directional relationships
- supporting theory cues

### Useful for

- concept clarification
- topic narrowing
- variable naming

## Model 2. Analytical Framework Model

### Purpose

Translate concepts into an analyzable research framework.

### Include

- research object
- key dimensions or variables
- mediators or moderators if appropriate
- observable indicators
- data sources
- likely analytic method

### Useful for

- method planning
- proposal writing
- data design

## Model 3. Paper-Writing Model

### Purpose

Show how the paper can be structured around the argument rather than around arbitrary section titles.

### Include

- problem entry point
- literature base
- theory anchor
- method route
- analysis chapters or subsections
- discussion and implication focus

## Relationship Types To Consider

- antecedent and outcome
- mediator
- moderator
- mechanism path
- contextual condition
- classroom conversion path

Do not force a causal diagram if the corpus supports only conceptual or interpretive analysis.

## Indicator Design Prompts

For each important variable or concept, ask:

1. How would this appear in classroom practice?
2. What data could capture it?
3. Is it better measured numerically, descriptively, or both?
4. What is the risk of over-abstracting it?

## Risk Checks

Common modeling problems include:

- concepts too broad to observe
- theory imported without adaptation
- causal language stronger than the data allows
- mismatch between model and available data
- paper structure not matching the real contribution

## Recommended Output Fields

For each model, specify:

- suitable research question
- theory basis
- concept or variable relations
- usable data
- likely risks
- suitable publication direction

FILE:references/ima_integration.md
# iMA Integration

## Integrity First

This package does not assume that `iMA` exposes an official API, MCP server, or CLI. Do not invent one. The skill should support `iMA` through honest, replaceable adapters.

## Supported Adapter Modes

### 1. iMA Export Folder Mode

Use this mode when the user exports materials from iMA into a local folder.

Recommended folder pattern:

```text
research_corpus/
├── literature/
├── notes/
├── observations/
├── interviews/
├── questionnaires/
├── policy/
└── manifest.md
```

Supported file types:

- `md`
- `txt`
- `pdf`
- `docx`
- exported article text

Recommended manifest fields:

| Field | Meaning |
| --- | --- |
| `source_id` | stable local ID such as `A01` or `D03` |
| `file_name` | local file name |
| `source_type` | article, dissertation, note, observation, interview, policy, etc. |
| `origin` | iMA export, local note, WeChat export, meeting record, and so on |
| `verification_status` | `已核验`, `部分核验`, `待核验` |
| `notes` | short description or retrieval reminder |

### 2. Local Research Corpus Mode

Use this when the user already keeps a folder such as `research_corpus/` outside iMA.

Recommended workflow:

1. Inventory files by subfolder.
2. Group by evidence class.
3. Extract working notes or source IDs.
4. Build the evidence chain table before synthesis.

### 3. Future API, MCP, Or CLI Adapter Mode

If iMA later exposes a verifiable integration surface, add a separate adapter note such as:

- `connectors/ima_adapter.md`
- `scripts/ingest_ima_export.py`
- `references/ima_api_notes.md`

Until then, any integration claim must stay conditional and clearly labeled as future work.

## File Handling Guidance

| File type | Handling suggestion |
| --- | --- |
| `md`, `txt` | read directly and preserve headings, note IDs, and dates |
| `pdf` | extract cautiously; if OCR or page structure is unreliable, mark key claims `待核验` |
| `docx` | extract text carefully and preserve section titles if possible |
| exported public articles | classify as `D` unless independently verified as academic publications |
| observation or interview records | preserve speaker or event context and anonymize if required |

## Safe Default Behavior

When the runtime cannot reliably read a format:

1. state the limitation
2. ask for export to `md` or `txt`, or
3. request a manually prepared excerpt

This is better than pretending the source was fully read.

## Suggested Source Register

Use a compact table like this during ingestion:

| Source ID | File | Class | Topic | Verification | Key usable content |
| --- | --- | --- | --- | --- | --- |
| A01 | | | | | |
| B01 | | | | | |
| D01 | | | | | |

## Notes For Future Integrators

- Keep adapter logic swappable.
- Keep the evidence hierarchy outside the adapter so trust rules do not depend on the transport layer.
- Separate ingestion from synthesis.
- Never let an integration script silently assign academic status to unknown materials.

FILE:references/research_gap_taxonomy.md
# Research Gap Taxonomy

## Goal

A useful gap statement should be specific enough to produce research questions and method choices, not just a generic sentence saying that existing studies are insufficient.

## Gap Types

| Gap type | Diagnostic question | Typical symptom |
| --- | --- | --- |
| Object gap | Who is missing from the literature? | high-school students, ordinary schools, rural or local samples, non-elite groups are underrepresented |
| Scene gap | Which real settings are thinly studied? | authentic classrooms, human-AI co-creation tasks, local-culture teaching scenes are underdescribed |
| Method gap | Which methods are missing or underused? | literature is dominated by conceptual discussion or surveys without classroom observation, action research, DBR, or mixed methods |
| Theory gap | Which lenses are weakly integrated? | creativity, aesthetic education, technology acceptance, curriculum theory, and music education theory remain disconnected |
| Data gap | Which data forms are absent? | classroom process data, student works, interviews, rating rubrics, logs, or longitudinal traces are missing |
| Practice gap | What cannot yet be turned into a usable teaching plan? | findings remain abstract and do not become a lesson path, activity sequence, or assessment routine |
| China-context gap | What does foreign literature fail to explain locally? | imported models do not fit Chinese curriculum standards, school routines, or local assessment expectations |
| Cross-disciplinary gap | Which fields are adjacent but not integrated? | AI music generation research and music education research lack stable shared frameworks |

## Gap Identification Heuristics

Check whether the literature:

- overfocuses on higher education or expert users
- underdescribes classroom processes
- treats technology as a tool without pedagogy
- measures outcomes without interpreting mechanisms
- discusses creativity without music-specific criteria
- references local culture without translating it into classroom design

## Gap To Question Conversion

| Gap type | Question pattern |
| --- | --- |
| Object gap | How do `X learners` in `Y setting` experience or perform `Z`? |
| Scene gap | What happens when `practice or tool` is implemented in `specific classroom scene`? |
| Method gap | What new insight appears if `underused method` is introduced into this topic? |
| Theory gap | How can `theory A` and `theory B` jointly explain `problem X`? |
| Data gap | What can be learned by adding `artifact, observation, or interview data` to current evidence? |
| Practice gap | How can existing findings be converted into a feasible curriculum or teaching design? |
| China-context gap | How should `foreign finding or model` be adapted to the Chinese high-school music context? |
| Cross-disciplinary gap | What framework can connect AI music generation and music education in a stable way? |

## Gap To Method Suggestions

| Gap type | Common methods |
| --- | --- |
| Object gap | case study, survey, interview, mixed methods |
| Scene gap | classroom observation, action research, DBR, case study |
| Method gap | introduce mixed methods, classroom observation, DBR, grounded coding |
| Theory gap | literature review, conceptual paper, mixed-method explanatory design |
| Data gap | artifact analysis, interview, observation, rubric scoring, quasi-experiment |
| Practice gap | DBR, action research, curriculum-development research |
| China-context gap | literature review plus local case study, mixed methods, policy-linked analysis |
| Cross-disciplinary gap | conceptual modeling, literature review, pilot classroom design |

## Recommended Matrix Fields

- gap type
- evidence basis
- concrete gap statement
- candidate research question
- feasible method
- expected data
- publication potential
- risk level

## Risk Level Heuristic

| Risk level | Meaning |
| --- | --- |
| Low | clear topic, accessible data, manageable scope |
| Medium | topic is promising but needs stronger evidence or tighter variables |
| High | data access, ethics, measurement, or theory alignment is uncertain |

FILE:references/evidence_hierarchy.md
# Evidence Hierarchy

## Goal

This hierarchy prevents the skill from blending academic evidence, public commentary, classroom material, and personal experience into a misleading single layer.

## Evidence Classes

| Class | Definition | Typical examples | Allowed use | Main caution |
| --- | --- | --- | --- | --- |
| `A` | Strong academic or authoritative evidence | peer-reviewed journal articles, verified dissertations, authoritative monographs, official policy documents, curriculum standards | support concept definitions, theory claims, method claims, and field consensus | still verify relevance, year, and context |
| `B` | Chinese core or particularly publication-relevant evidence | CSSCI, Peking University core journals, authoritative education journals, high-value Chinese policy or curricular commentary | support China-context positioning, journal framing, domestic literature mapping | do not assume all domestic journals are core |
| `C` | Mid-tier research and institutional evidence | conference papers, think-tank or institutional reports, project summaries, white papers | support trend signals, implementation cases, emerging topics | may not be peer reviewed or stable |
| `D` | Practice or public-facing materials | WeChat public articles, interviews, lesson observations, meeting notes, teaching logs, workshop records | support scene description, practice insight, hypothesis generation, contextual interpretation | cannot be presented as established research consensus |
| `E` | Personal or experiential material | user reflections, field impressions, initial intuitions, undocumented anecdotes | support idea generation and reflexive notes | must not be elevated into literature conclusions |

## How To Cite Within Draft Analysis

Use source IDs during working synthesis:

- `[A01]`
- `[B03]`
- `[C02]`
- `[D05]`
- `[E01]`

If a claim mixes source types, preserve that mixture explicitly, for example:

- `Student engagement was discussed in verified literature [A02][B01] and echoed in classroom notes [D03].`

## Verification Labels

Add one of these tags when needed:

- `已核验`: source identity and type are reasonably confirmed
- `部分核验`: some metadata is confirmed but the full text or publication status is incomplete
- `待核验`: not enough information to verify

## Non-Negotiable Rules

1. Do not fabricate bibliographic metadata.
2. Do not upgrade `D` or `E` sources into `A` or `B`.
3. Do not hide uncertainty when a source is only partially accessible.
4. Do not treat media commentary as equivalent to peer-reviewed evidence.
5. Do not present the user's experience as prior scholarship.

## Evidence Use By Output Type

| Output type | Preferred evidence | Supplemental evidence | Not enough on its own |
| --- | --- | --- | --- |
| Literature review | `A`, `B` | `C` for emerging trends | `D`, `E` |
| Theory or concept model | `A`, `B` | `C`, `D` for contextual anchoring | `E` |
| Research gap matrix | `A`, `B`, `C` | `D` for practice gaps and scene gaps | `E` |
| Opening report | `A`, `B` | `C`, `D` where context matters | `E` |
| Classroom-practice design | `A`, `B`, `D` | `C` | `E` alone |

## Recommended Working Sequence

1. Build an evidence inventory.
2. Mark each source class.
3. Flag anything `待核验`.
4. Write claims with source IDs attached.
5. Only convert working IDs into full citations after the user confirms or provides bibliographic details.

FILE:references/literature_review_principles.md
# Literature Review Principles

## Goal

A strong review should explain how a field is organized, where it agrees, where it disagrees, and what remains unresolved. It should not read like a sequence of isolated author summaries.

## Required Structure

The preferred review sequence is:

1. Concept definition
2. Domestic research trajectory
3. International research trajectory
4. Main theory lenses
5. Main methods used
6. Shared findings or consensus
7. Disputes and disagreements
8. Limitations or blind spots
9. Implications for the user's topic

## Organizing Dimensions

The skill should synthesize by one or more of these dimensions:

- theme
- concept
- theory
- method
- scene
- controversy
- gap

Avoid a default `Author A said... Author B said...` pattern unless the user explicitly asks for a chronological bibliography summary.

## Domestic And International Paths

When both are relevant:

- keep domestic and international trajectories distinguishable
- compare their concepts, methods, and contexts
- identify translation problems between them
- note whether foreign findings need Chinese classroom adaptation

## Review Writing Heuristics

### Concept Definition

Clarify:

- which concept is stable
- which concept is contested
- which terms are used inconsistently

### Theory Lens Review

Ask:

- which theories dominate the field
- which theories are imported from adjacent fields
- which theories are absent but potentially useful

### Method Review

Track:

- which methods dominate
- which methods are underused
- whether classroom-process evidence is thin
- whether creative products, interviews, or mixed evidence are missing

### Dispute Review

Look for disagreements about:

- construct definitions
- effectiveness claims
- transferability across contexts
- measurement standards
- technology effects

## Output Sequence

1. `综述结构表`
2. `可直接扩写的综述段落`
3. `引用与证据清单`

## Integrity Rules

- Keep source class visible near major claims.
- Mark any unverified item `待核验`.
- If the corpus is thin, say so.
- Distinguish literature conclusions from user field notes.