Learning Resource Recommender

Learning Resource Recommender

Core Rule

Recommend resources as a learning decision, not a link dump. Use IELTS Buddy state and the learner's current weakness first, then choose a small number of external resources that fit the skill, level, time budget, and learning mode.

The learning-resource catalog is bundled in this Skill and maintained by the repository developer. Do not depend on external local paths or ask the learner to provide the catalog.

Inputs

Use any available combination:

• IELTS Buddy route progress, weak skills, vocabulary progress, or recent practice errors.
• User goal: IELTS band, CEFR level, target skill, accent preference, topic interest, available minutes.
• The bundled catalog at references/learning-english-catalog.md.
• Direct resource candidates supplied in chat.

Workflow

1. Identify the learner's current need:

• listening input;
• pronunciation/speaking;
• reading input;
• writing support;
• vocabulary;
• grammar;
• exam-specific IELTS practice;
• background immersion.

1. Run scripts/extract_learning_resource_catalog.py without a path to read the bundled catalog.
2. Filter candidates by:

• target skill;
• level or difficulty cues;
• IELTS relevance;
• availability of transcripts/subtitles/exercises;
• cognitive load and time budget;
• whether the learner needs input, output, or review.

1. Recommend 3-7 resources only.
2. For each resource, explain:

• why this resource fits the current need;
• how to use it this week;
• what output or review artifact to bring back to the Agent.

1. Prefer official, stable, learner-friendly resources when choices are close.
2. If a resource is entertainment-first, label it as immersion, not IELTS practice.

Default Output

Use concise chat for quick recommendations. When the user asks for a study pack, weekly resource plan, or printable recommendation list, deliver a validated .docx.

1. Build a recommendation plan.
2. Generate the DOCX with scripts/create_resource_recommendations_docx.py.
3. Validate it with scripts/validate_resource_recommendations_docx.py.
4. Return the absolute path to the final DOCX.

Bundled Resources

• scripts/extract_learning_resource_catalog.py: parse a Markdown resource catalog into JSON candidates with title, URL, description, and heading path.
• scripts/create_resource_recommendations_docx.py: create a recommendation DOCX with ranked resources and a weekly usage plan.
• scripts/validate_resource_recommendations_docx.py: verify required sections, tables, Times New Roman, and plan content.
• references/learning-english-catalog.md: bundled developer-maintained external learning-resource catalog.

JSON Recommendation Plan

{
  "learner_goal": "IELTS Listening Band 7.0",
  "focus": "listening",
  "level": "B1-B2",
  "time_budget": "30 minutes/day",
  "rationale": "The learner needs transcript-supported listening and paraphrase review.",
  "recommendations": [
    {
      "rank": 1,
      "title": "BBC 6 Minute English",
      "url": "https://www.bbc.co.uk/learningenglish/english/features/6-minute-english",
      "category": "听力学习 / 播客资源",
      "fit": "Short episodes with learner-friendly topics and transcripts.",
      "how_to_use": "Listen once without transcript, then mark 5 paraphrases from the transcript.",
      "bring_back": "Three new phrases and one sentence you failed to catch."
    }
  ],
  "weekly_plan": [
    "Day 1-2: BBC 6 Minute English transcript listening.",
    "Day 3-4: One IELTS listening section and error notebook."
  ]
}

python scripts/extract_learning_resource_catalog.py --skill listening --limit 30
python scripts/create_resource_recommendations_docx.py resource_recommendation_plan.json
python scripts/validate_resource_recommendations_docx.py ~/Desktop/IELTS_Resource_Recommendations_YYYYMMDD_HHMM.docx --plan-json resource_recommendation_plan.json

Quality Bar

• Do not recommend more than seven resources at once.
• Do not treat general English resources as IELTS materials unless they train a concrete IELTS subskill.
• Include a use method, not just a URL.
• Prefer bundled-catalog parsing over web browsing for normal recommendations.

Source & license

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

• Author: Jobo16
• Source: Jobo16/ielts-all-in-one-skills
• License: MIT
• Homepage: https://ieltsbuddy.igocn.cn

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