Language Learning
Story Agent

Give it vocabulary words in your target language, get short stories using all of them with translations below. Built with OpenCode in under 20 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

You'll also need: Some vocabulary words in whatever language you're learning.

What You'll Build

By the end of this guide, you'll have a command-line tool that turns vocabulary lists into memorable short stories. It will:

  • Accept a list of vocabulary words in your target language (Spanish, French, German, etc.)
  • Generate a short story (200-300 words) that naturally uses every word on your list
  • Provide an English translation directly below the story
  • Bold the vocabulary words in both versions so they stand out
  • Save stories to files so you can review them later

This is a personal study tool. You give it the words you're struggling with, it weaves them into a story that's easier to remember than flashcards. Then you iterate with OpenCode to add quizzes, difficulty levels, and more.

1

Create Your Project

Set up a project folder with an AGENTS.md file that tells OpenCode what kind of tool you're building.

mkdir -p ~/projects/language-story
cd ~/projects/language-story
mkdir -p ~/projects/language-story
cd ~/projects/language-story

Now create an AGENTS.md file. This is the context file that OpenCode reads to understand your project:

# Language Learning Story Agent

## Project Type
Python CLI tool

## Description
A command-line tool that takes a list of vocabulary words in a target
language and generates a short story (200-300 words) using all of them,
with an English translation below. Designed for language learners who
want to see words used in context.

## Tech Stack
- Python 3.8+ (standard library only, no external deps)
- argparse for CLI interface
- JSON for saving story history

## Conventions
- Use type hints
- Keep it in a single file for simplicity
- Default target language is Spanish (configurable via flag)
- Bold vocabulary words in the output using markdown **word**
- Support multiple output formats: terminal, markdown file, plain text

Save this as AGENTS.md in your project folder. You can create it manually or use OpenCode:

opencode
Why AGENTS.md?
OpenCode reads this file automatically when you start it in the project directory. It gives the AI context about your project's purpose, tech stack, and conventions -- so every response is more relevant and accurate.
2

Build the Story Generator

With OpenCode running in your project folder, give it the task. One prompt builds the whole thing.

Type this into OpenCode:

Create a Python script that takes a list of Spanish vocabulary words and writes a short story (200-300 words) using all of them, with an English translation below

That's the simple version. For a more complete tool, try this expanded prompt:

Create a Python script called story_gen.py that generates language
learning stories from vocabulary words.

Usage:
  python3 story_gen.py --words "perro, correr, parque, feliz, agua"
  python3 story_gen.py --file vocab_list.txt --lang french

The script should:
1. Accept words via --words (comma-separated) or --file (one per line)
2. Support a --lang flag for target language (default: spanish)
3. Generate a short story (200-300 words) in the target language
   that uses ALL the provided vocabulary words naturally
4. Bold each vocabulary word in the story with markdown **word**
5. Print the story followed by an English translation (also with
   the translated vocabulary words bolded)
6. Include a vocabulary reference table at the end:
   Word | Translation | Part of Speech
7. Support --save to write output to a .md file with a timestamp

Include at least 3 pre-built story templates (a day at the market,
a journey through the city, a conversation between friends) that
the script selects from based on which words fit best.

OpenCode will generate a complete Python script. You'll see it write the file in real time. When it's done, you'll have a working story_gen.py in your project folder.

What OpenCode Generates

The output will typically include:

  • A StoryGenerator class with methods for story creation and translation
  • Pre-built story templates with placeholder slots for vocabulary words
  • Vocabulary word bolding in both the story and translation
  • A reference table mapping each word to its English translation
  • File output with timestamps so you can build a collection over time
3

Run and Iterate

Test with some vocabulary words, review the story, and improve it with follow-up prompts.

Run your story generator with some Spanish words:

python3 story_gen.py --words "perro, correr, parque, feliz, agua, amigo, sol, caminar"

You should see output like this:

## Historia: Un Dia en el Parque

Era una manana brillante y el **sol** calentaba la ciudad. Mi
**amigo** Carlos me llamo por telefono. "Vamos a **caminar** al
**parque**," dijo con voz **feliz**. Yo acepte inmediatamente.

Cuando llegamos, vimos un **perro** grande jugando cerca del lago.
El **perro** estaba tan emocionado que empezo a **correr** en
circulos alrededor de nosotros. Carlos se rio y le lanzo un palo.

Despues de **caminar** por una hora, teniamos sed. Compramos una
botella de **agua** fria del vendedor y nos sentamos bajo un arbol.
Mi **amigo** dijo que este era el mejor dia del verano. Yo estaba
de acuerdo -- me sentia muy **feliz**.

---

## Translation: A Day at the Park

It was a bright morning and the **sun** warmed the city. My
**friend** Carlos called me on the phone. "Let's **walk** to the
**park**," he said with a **happy** voice. I accepted immediately.

When we arrived, we saw a big **dog** playing near the lake. The
**dog** was so excited that it started to **run** in circles around
us. Carlos laughed and threw it a stick.

After **walking** for an hour, we were thirsty. We bought a bottle
of cold **water** from the vendor and sat under a tree. My **friend**
said this was the best day of summer. I agreed -- I felt very **happy**.

---

## Vocabulary Reference
| Word | Translation | Part of Speech |
|------|-------------|----------------|
| perro | dog | noun |
| correr | to run | verb |
| parque | park | noun |
| feliz | happy | adjective |
| agua | water | noun |
| amigo | friend | noun |
| sol | sun | noun |
| caminar | to walk | verb |

Iterate with OpenCode

Found something you want to change? Go back to OpenCode and ask. The AI remembers your project context from AGENTS.md.

# Example iteration prompts:
Add accents and special characters to the Spanish text so
it reads correctly (manana -> mañana, etc.)

Add a --theme flag so I can request stories about specific
topics like "food", "travel", "work", or "school".

Track which words I've practiced in a JSON file and tell me
which ones I haven't reviewed recently.
Version control tip
Initialize a git repo with git init and commit after each working version. Store it on GitHub for free. That way you can always roll back if an iteration breaks something.

Example Prompts to Try

Once your basic story generator works, try these prompts to extend it. Each one is a separate prompt you can copy and paste into OpenCode:

Add difficulty levels: beginner stories use simple grammar, advanced use subjunctive
Generate vocabulary quiz questions from the story
Create a flashcard set in CSV format
Write a dialogue between two characters instead of a narrative
Add a pronunciation guide with phonetic spelling next to
each vocabulary word in the reference table
Create a fill-in-the-blank exercise where the vocabulary words
are removed from the story and listed as options below

Each prompt builds on the existing code. OpenCode reads the current state of story_gen.py and modifies it in place.

What's Next?

You've built a working language learning story generator. Here's where to go from here:

  • Build a daily habit: Add 5-10 new words each day, generate a story, and read it during your morning coffee. The stories give context that pure flashcards can't.
  • Export for Anki: Ask OpenCode to add CSV export compatible with Anki flashcard format. Import your stories and vocabulary directly into spaced repetition.
  • Deploy it: Wrap it in a simple web interface with Flask and host it for free on Cloudflare Pages.
  • Try another agent: The setup is the same -- only the task changes. Pick your next project:

Ready for the Next Agent?

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build README Generator All Guides