reference-generator

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:

# 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:

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:

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:

# 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):

## 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.

# 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.