How to Contribute to shareAI-lab/learn-claude-code: A Complete Guide

To contribute to shareAI-lab/learn-claude-code, fork the repository, create a feature branch following the progressive session architecture, and ensure your changes pass the CI pipeline by maintaining PEP 8 compliance and TypeScript type safety.

The shareAI-lab/learn-claude-code repository is a teaching-focused codebase that demonstrates how to build a Claude-Code-style autonomous agent step-by-step. Contributing effectively requires understanding its unique progressive session structure, where each lesson builds upon the previous one without modifying core loop mechanics.

Understanding the Repository Architecture

Before you contribute to shareAI-lab/learn-claude-code, familiarize yourself with how the codebase organizes its teaching materials and runtime components.

Core Agent Implementations

The heart of the repository lives in the agents/ directory, containing progressive sessions (s01 through s12) and the capstone agents/s_full.py. The file agents/s01_agent_loop.py contains the minimal loop implementation that serves as the foundation for all sessions, while agents/s_full.py composes every advanced mechanism including tasks, background processing, teammates, and compression.

Documentation Structure

Documentation follows a mental-model-first approach available in three languages (EN, ZH, JA). Each session has a corresponding markdown file in docs/en/ (e.g., docs/en/s01-the-agent-loop.md, docs/en/s02-tool-use.md). When adding features, you must update or create corresponding documentation pages following the existing structure: header, problem statement, solution diagram, and minimal code examples.

Skills System

The repository implements a declarative skill system where capabilities are defined in Markdown files. Skills reside in skills/<category>/SKILL.md (e.g., skills/pdf/SKILL.md). The SkillLoader class in agents/s_full.py automatically discovers these files at runtime, making it easy to extend agent capabilities without modifying core logic.

Web UI and CI Pipeline

A Next.js visualizer in the web/ directory provides a graphical interface for stepping through sessions. The continuous integration pipeline defined in .github/workflows/ci.yml type-checks the web UI and builds it on every push, ensuring TypeScript strictness across the JavaScript components.

Setting Up Your Development Environment

To begin contributing to shareAI-lab/learn-claude-code, configure your local environment with the necessary dependencies and API access.

First, fork the repository on GitHub, then clone your fork locally:

git clone https://github.com/<your-username>/learn-claude-code.git
cd learn-claude-code

Install the Python dependencies and configure your environment:

pip install -r requirements.txt
cp .env.example .env

Edit the .env file to add your ANTHROPIC_API_KEY. Never commit this file to version control.

Contributing Code to shareAI-lab/learn-claude-code

When modifying the codebase, respect the progressive architecture where each session builds upon previous lessons without altering core loop mechanics.

Working with Progressive Sessions

Each file in agents/s0X_*.py represents a specific teaching milestone. When contributing new functionality:

• Extend the capstone agents/s_full.py for production-ready features
• Create new session files only when introducing fundamental new concepts
• Maintain the existing TOOL_HANDLERS dispatch pattern found in agents/s_full.py
• Mirror the agent loop exit pattern from agents/s01_agent_loop.py: if response.stop_reason != "tool_use": return

Adding New Tools

To add a tool like git_status that returns repository status:

First, implement the handler in agents/s_full.py:

def run_git_status() -> str:
    return subprocess.run(
        "git status", 
        shell=True,
        cwd=WORKDIR, 
        capture_output=True,
        text=True, 
        timeout=30
    ).stdout.strip()

Next, register the tool in the TOOL_HANDLERS dictionary near line 776:

"git_status": lambda **kw: run_git_status(),

Then add the tool definition to the TOOLS list:

{
  "name": "git_status",
  "description": "Return `git status` of the repository.",
  "input_schema": { "type": "object", "properties": {} }
}

Finally, document the tool in docs/en/s02-tool-use.md with a usage example.

Creating New Skills

Skills require no code changes—only Markdown files. Create skills/<category>/SKILL.md:

---
name: Example Skill
description: Demonstrates how to add a simple skill.
---

This skill simply returns the string "Hello from Example Skill!".

The SkillLoader in agents/s_full.py automatically discovers and loads these files at runtime.

Documentation Requirements

Every code contribution requires corresponding documentation updates:

• New sessions need pages in docs/en/ following the structure: header, problem statement, solution diagram, minimal code
• New tools require updates to docs/en/s02-tool-use.md
• API changes need updates to relevant documentation pages

Testing and Validation

Before submitting your contribution to shareAI-lab/learn-claude-code, validate your changes locally.

Run a specific teaching session to verify functionality:

python agents/s05_skill_loading.py

This starts an interactive REPL (see the if __name__ == "__main__" block in each script). Test your changes by typing natural language requests:

s05 >> Load the PDF skill and summarize the first page.

Validate the web UI TypeScript compilation:

cd web
npm ci
npx tsc --noEmit

Submitting Your Contribution

Follow the standard GitHub workflow when contributing to shareAI-lab/learn-claude-code.

Create a feature branch with a descriptive name:

git checkout -b feat/add-git-status-tool

Commit your changes following conventional commit format:

git add agents/s_full.py docs/en/s02-tool-use.md
git commit -m "feat: add git_status tool for repository introspection"
git push origin feat/add-git-status-tool

Open a Pull Request targeting the main branch:

• Use a concise title (feat: … or fix: …)
• Explain why the change is needed
• Reference relevant files (e.g., agents/s_full.py, docs/en/...)
• Mention any new tests or validation steps

The CI pipeline will automatically run type-checking and web builds. If checks fail, fix issues locally and push new commits to the branch.

Common Pitfalls and Troubleshooting

When contributing to shareAI-lab/learn-claude-code, avoid these frequent issues:

Symptom	Likely cause	Fix
CI fails on npx tsc	Missing TypeScript dev dependencies or syntax error in a .tsx file	Run npm ci in web/ and fix the syntax error
Runtime ValueError: Path escapes workspace	A new file operation uses a relative path that climbs outside the project directory	Use safe_path() from agents/s_full.py to resolve paths
Agent loop never exits	Forgetting to return when response.stop_reason != "tool_use" in a custom session script	Mirror the pattern used in agents/s01_agent_loop.py (if response.stop_reason != "tool_use": return)
LLM API key missing	.env not set or ANTHROPIC_API_KEY typo	Add ANTHROPIC_API_KEY=your_key to .env (do not commit the key)

Summary

Contributing to shareAI-lab/learn-claude-code requires understanding its progressive teaching architecture and maintaining the integrity of its core agent loop. Key takeaways include:

• Respect the session structure: Extend agents/s_full.py for production features, and only create new s0X_*.py files for fundamental new concepts
• Follow existing patterns: Use the TOOL_HANDLERS dispatch mechanism and mirror the loop exit logic from agents/s01_agent_loop.py
• Document everything: Every code change requires corresponding updates to docs/en/ following the mental-model-first structure
• Validate locally: Test sessions with python agents/s05_skill_loading.py and verify TypeScript with npx tsc --noEmit before submitting
• Keep CI green: Ensure PEP 8 compliance for Python and strict TypeScript typing for the Next.js web UI

Frequently Asked Questions

What is the best way to start contributing to shareAI-lab/learn-claude-code?

Begin by running the existing teaching sessions locally to understand the progressive architecture. Start with python agents/s01_agent_loop.py to see the minimal implementation, then progress through s02 through s12 before attempting to modify agents/s_full.py. This ensures you understand how each mechanism builds upon the core loop without breaking existing functionality.

How do I add a new tool to the agent without breaking existing sessions?

Implement your tool handler in agents/s_full.py following the existing pattern, register it in both the TOOL_HANDLERS dictionary and the TOOLS JSON schema list near line 776, and ensure it uses safe_path() for any file operations to prevent path traversal. Do not modify the core loop logic in agents/s01_agent_loop.py or earlier session files, as these serve as immutable teaching references.

What documentation is required when contributing new features?

Every code contribution must include corresponding documentation in docs/en/ following the mental-model-first structure: a clear header, problem statement, solution diagram, and minimal code example. New tools require updates to docs/en/s02-tool-use.md, while new sessions need dedicated pages explaining the concept. The documentation must align with the existing three-language support pattern (EN, ZH, JA) when possible.

Why does my agent loop run indefinitely when testing locally?

The agent loop runs indefinitely when the exit condition if response.stop_reason != "tool_use": return is missing or incorrectly implemented. Ensure your session script mirrors the pattern from agents/s01_agent_loop.py, checking the stop_reason attribute after each LLM call and returning control to the user when no tool use is requested. Also verify that your ANTHROPIC_API_KEY is correctly set in .env to prevent authentication-related hangs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}