reference-generator skill

---
name: reference-generator
description: This skill generates curated, verified reference lists for textbooks with level-appropriate resources (10 for junior-high, 20 for senior-high, 30 for college, 40 for graduate). References are formatted with links, publication details, and relevance descriptions. Use this skill when working with intelligent textbooks that need academic references, either book-level or chapter-level.
---

# Reference Generator

## Overview

Generate high-quality, verified reference lists for educational textbooks with level-appropriate content and quantity. The skill analyzes course descriptions to determine the target audience and creates references that match the readers' level, from fun and engaging resources for junior-high students to authoritative peer-reviewed papers for graduate students.

## When to Use This Skill

Use this skill when:

- Creating a new intelligent textbook that needs a comprehensive reference list
- Adding references to an existing textbook
- Updating or expanding references for educational content
- A user explicitly requests reference generation

## Reference Generation Workflow

### Step 1: Analyze the Course Description

Read the `/docs/course-description.md` file to determine:

- **Grade level** or target audience (junior-high, senior-high, college, graduate)
- **Prerequisites** - indicates reader sophistication
- **Subject matter** - determines reference topics
- **Learning objectives** - guides reference selection

The grade level determines:

- **Junior-high (middle school)**: 10 references - fun, engaging, visual resources
- **Senior-high (high school)**: 20 references - mix of accessible and academic sources
- **College (undergraduate)**: 30 references - more academic, some peer-reviewed papers
- **Professional Development**: 30 references - more academic, some peer-reviewed papers
- **Graduate (masters/PhD)**: 40 references - heavily peer-reviewed, authoritative sources

### Step 2: Check for Chapter-Level Content

Before generating references, search for chapter content in the textbook:

```bash
# Look for the chapters directory
find /docs/chapters
# Look for chapter files
find /docs -name "chapter*.md" -o -name "*-chapter-*.md"
```

If chapter content exists, use the AskUserQuestion tool to ask:
- "Would you like book-level references (in /docs/references.md) or chapter-level references (at the end of each chapter)?"

### Step 3: Generate References with Verification

For each reference, perform the following:

1. **Search for authoritative sources** using WebSearch tool
2. **Verify each URL** using WebFetch to ensure the link is valid and accessible
3. **Format according to the standard template** (see Format Specification below)

**Quality Guidelines by Level:**

**Junior-High (10 references):**
- Educational websites with interactive content
- Videos from reputable educational channels
- Visual resources, infographics, and animations
- Age-appropriate articles from educational publishers
- Museums, science centers, and educational organizations

**Senior-High (20 references):**
- Mix of educational websites and academic sources
- Reputable news organizations and science journalism
- Educational videos and documentaries
- Introduction to academic journals (more accessible papers)
- Government and NGO educational resources

**College (30 references):**
- Peer-reviewed journal articles (50%+ of references)
- Academic textbooks and monographs
- University course materials and lectures
- Research institution publications
- Industry white papers and technical reports

**Graduate (40 references):**
- Heavily weighted toward peer-reviewed journals (70%+ of references)
- Seminal papers in the field
- Recent research (last 5 years) showing current state of field
- Meta-analyses and systematic reviews
- Academic books from university presses

### Step 4: Format Each Reference

Use the following format for every reference:

```markdown
1. [Link Title](URL) - YYYY-MM-DD - Publication Name - Brief description of resource and specific relevance to the textbook topic.
```

**Format Specifications:**
- **Link Title**: Exact title of the article, paper, video, or resource
- **URL**: Verified, working link (use WebFetch to confirm)
- **Date**: Publication date in YYYY-MM-DD format (use YYYY-MM or YYYY if day/month unavailable)
- **Publication Name**: Journal, website, organization, or publisher
- **Description**: 1-2 sentences explaining what the resource covers and why it's relevant to this specific textbook

**Example References:**

```markdown
1. [How Neural Networks Really Work](https://distill.pub/2020/circuits/zoom-in/) - 2020-03-10 - Distill - Interactive visualization explaining the inner workings of neural networks through explorable explanations, perfect for visual learners beginning their ML journey.

2. [Attention Is All You Need](https://arxiv.org/abs/1706.03762) - 2017-06-12 - arXiv - Seminal paper introducing the Transformer architecture that revolutionized natural language processing and forms the foundation for modern LLMs like GPT and BERT.

3. [Khan Academy: Introduction to Algorithms](https://www.khanacademy.org/computing/computer-science/algorithms) - 2024-01-15 - Khan Academy - Free, interactive course covering fundamental algorithms including sorting and searching, with visualizations and practice exercises suitable for high school students.
```

### Step 5: Write References to File

**For book-level references:**
Create or overwrite `/docs/references.md` with:

```markdown
# References

This textbook draws upon the following high-quality resources:

[Generated numbered list of references]

---
*References last updated: [Current Date]*
```

**For chapter-level references:**
Append to each chapter file (e.g., `/docs/chapters/01-introduction/index.md`):

```markdown

## References

[Generated numbered list of references for this chapter]
```

### Step 6: Validation and Reporting

After generating references:

1. **Count the references** to ensure correct quantity for level
2. **Verify all URLs** were checked with WebFetch
3. **Report summary** to user:
   - Number of references generated
   - Target level identified
   - File location
   - Any URLs that failed verification (if any)

## URL Verification Process

**Critical**: Every URL must be verified before inclusion.

```python
# Use WebFetch for each URL
WebFetch(url=reference_url, prompt="Is this page accessible? Provide the title and a brief description of the content.")
```

If a URL returns an error or redirect:
- Try to find an updated or archived version
- Use Internet Archive / Wayback Machine if appropriate
- Skip the reference if no valid URL exists
- Note in the report any references that couldn't be verified
- For academic papers, the full document might be behind a paywall.  Just reference the citation for these resources.  Prefer references on reputable sites like Google Scholar.
- For academic textbooks, prefer references that have many citations.

## Reference Quality Checklist

Before finalizing references, ensure:
- [ ] Correct quantity for target level (10/20/30/40)
- [ ] All URLs verified and accessible
- [ ] Publication dates included
- [ ] Mix of resource types (articles, videos, papers)
- [ ] Descriptions explain relevance to textbook
- [ ] Academic rigor matches target audience
- [ ] No duplicate sources
- [ ] Proper formatting throughout

## Example Usage Scenarios

**Scenario 1: New textbook**

```
User: "Generate references for my textbook"
→ Read /docs/course-description.md
→ Identify level (e.g., college)
→ Check for chapters (none found)
→ Generate 30 verified references
→ Write to /docs/references.md
```

**Scenario 2: Existing textbook with chapters**

```
User: "Add references to my course"
→ Read /docs/course-description.md
→ Find chapter files exist
→ Ask: "Book-level or chapter-level references?"
→ User selects chapter-level
→ Generate references for each chapter
→ Append to each chapter file
```

## Finish

- Report the number of references generated and indicate the number of working links
- Tell the user that for academic papers, a citation graph skill can be used create a list of the most highly sited papers that influence this topic

## Resources

This skill uses web-based verification tools built into Claude Code:
- **WebSearch**: Find authoritative sources on topics
- **WebFetch**: Verify URLs are accessible and extract metadata
- **AskUserQuestion**: Clarify book-level vs chapter-level preference

No additional scripts, references, or assets are required for this skill.