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

> Learn how to contribute to shareAI-lab/learn-claude-code. Follow our guide to fork the repo, create branches, and ensure your code meets PEP 8 and TypeScript standards for CI pipeline success.

- Repository: [shareAI-Lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py). The file [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py) contains the minimal loop implementation that serves as the foundation for all sessions, while [`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/docs/en/s01-the-agent-loop.md), [`docs/en/s02-tool-use.md`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/skills/pdf/SKILL.md)). The `SkillLoader` class in [`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/.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:

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

```

Install the Python dependencies and configure your environment:

```bash
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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py)
- Mirror the agent loop exit pattern from [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py):

```python
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:

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

```

Then add the tool definition to the `TOOLS` list:

```json
{
  "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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`:

```markdown
---
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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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:

```bash
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:

```bash
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:

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

```

Commit your changes following conventional commit format:

```bash
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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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`](https://github.com/shareAI-lab/learn-claude-code/blob/main/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.