forge-learn

Learn to customize your AI by editing text files.

You edit a file. The AI reads it. That's all that happens.

Why Text Files?

No build step — change a file, restart the session, done. Every instruction is git-diffable, inspectable without running anything, and works across AI tools (Claude Code, Gemini CLI, Codex, OpenCode). There is no framework to learn, no API to call, no schema to compile. The files are the system.

What Is This?

When you use an AI coding tool like Claude Code, every conversation starts from scratch — the AI doesn't know your name, your preferences, or what you're working on. You repeat yourself every session.

forge-learn fixes that. It's a collection of plain text files that your AI reads automatically. You tell it who you are once, and it remembers. You add skills — small instruction files — and it learns new abilities.

Everything here is a text file you can open, read, and edit. No magic, no hidden configuration, no compilation. If you can edit a document, you can customize your AI.

Supported Tools

forge-learn is built for Claude Code — skills are auto-discovered and slash commands (/Tour, /Explain, etc.) work out of the box.

The identity files (rules/Identity.md, Goals.md) and CLAUDE.md are plain markdown, so they're useful with other AI coding tools too — but skill discovery varies:

Tool	Reads CLAUDE.md	Skills as /commands	Install
Claude Code	Yes	Yes (full plugin support)	curl -fsSL https://claude.ai/install.sh | bash
OpenCode	Yes (fallback)	Partial (.claude/skills/)	curl -fsSL https://opencode.ai/install | bash
Codex CLI	No (uses AGENTS.md)	No (Uses $Skill "command" instead)	See Codex docs
Gemini CLI	No (uses GEMINI.md)	No	See Gemini CLI docs
GitHub Copilot	No (uses .github/copilot-instructions.md)	No	Via IDE

For tools that don't read CLAUDE.md, you can copy the content into their instruction file format (e.g., AGENTS.md for Codex, GEMINI.md for Gemini CLI).

What's Inside

rules/      <- Who you are and what you care about
skills/        <- What your AI can do (commands you can run)
agents/        <- AI personas (e.g., CodeHelper)

Steering is your identity. Open rules/Identity.md, change the name to yours, and save. Next session, your AI greets you by name.

Skills are actions. Type /Tour and your AI walks you through everything. Type /Explain and it breaks down any file or error in plain language.

Agents are personas. The starter agent CodeHelper explains broken code in plain language. You can edit it or create your own.

Quick Start

1. Install Claude Code

Mac / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Mac (Homebrew):

brew install --cask claude-code

Windows (WinGet):

winget install Anthropic.ClaudeCode

2. Download this project

Open a terminal (Mac: Terminal app, Windows: PowerShell or Git Bash) and paste:

git clone https://github.com/N4M3Z/forge-learn.git
cd forge-learn

This creates a forge-learn directory on your computer and moves into it.

Don't have Git? Mac: type git --version in Terminal and macOS will prompt you to install it. Windows: download from git-scm.com.

3. Set up

Let your AI do it (recommended): Start Claude Code and ask it to follow INSTALL.md — it checks prerequisites, personalizes your identity files, deploys skills, and runs /Tour.

claude
# then tell it: "Set up forge-learn for me. Follow INSTALL.md."

Or do it yourself:

1. Open rules/Identity.md in any text editor — change Your Name to your actual name and save
2. Open rules/Goals.md — replace the example goals with yours
3. Deploy agents and skills:
   • Mac/Linux/WSL/Git Bash: run make install
   • Windows PowerShell fallback: run the Windows block in INSTALL.md (cargo build --release + install-*.exe)
4. Start Claude Code: claude
5. Type /Tour

That's it. You're set up.

Optional: Make skills available everywhere

By default, skills only work inside the forge-learn directory. To use /Explain, /GitHelp, and other skills in any project:

make install SCOPE=user

This installs skills globally so they're available whenever you run claude, regardless of which project you're in.

Available Skills

Skill	What it does
/Tour	Walks you through your setup and available skills
/Progress	Shows your current level and suggests what to try next
/Explain	Explains any file, error, or concept in plain language
/FixIt	Diagnoses problems and proposes fixes
/GitHelp	Translates plain English into git commands
/Kickstart	Turns "I want to build X" into a plan with starter files
/Summarize	Extracts key points into a structured summary

Learning Path

forge-learn has a 7-level progression from your first skill modification to ecosystem contributor. Type /Progress anytime to see where you are and what to try next.

Level	Name	What you learn
1	Discover	Run a skill, read its source, change one line
2	Personalize	Edit identity files, see the AI adapt to you
3	Navigate	Work with files and save your progress
4	Build	Create projects from ideas
5	Author	Write custom rules, skills, and agents
6	Connect	Expand with optional modules
7	Forge	Contribute improvements to the ecosystem

See rules/Levels.md for the full roadmap with progress tracking.

How It Works

When you start a session, your AI tool reads these files before you say anything:

1. CLAUDE.md — ground rules and conventions (read automatically by Claude Code)
2. rules/Identity.md — your name, language, experience level (frontmatter parsed at session start)
3. rules/Goals.md — what you're working toward
4. Any other .md files in rules/ — custom rules you add

Skills (skills/*/SKILL.md) are registered as commands during plugin discovery. When you invoke a skill (e.g., /Explain in Claude Code, $Explain in Codex), the tool loads that skill's SKILL.md and follows its instructions. No runtime interpretation — the file IS the instruction.

Agents (agents/*.md) are specialist personas deployed by make install into provider-specific directories.

You change a file, the AI's behavior changes. There is no hidden layer between the file and the behavior.

Privacy Note

The rules/ files are yours to edit with personal information (your name, goals, preferences). If you plan to push this repository to a public GitHub account, be aware that anything you write in these files will be visible. Consider keeping your fork private, or review your rules files before pushing.

Want More?

Once you're comfortable, expand your setup with optional modules:

Module	What it adds
forge-text	12 text processing skills — translate, simplify, grammar fix, expand, condense, and more
forge-council	Multi-specialist code review — a panel of experts debates your changes
forge-avatar	Deep identity — digital avatar, beliefs, strategies, communication preferences
forge-core	Developer toolkit — build your own skills, agents, and modules

Clone a module and ask your AI to help set it up. For automated module management, see forge-user.

Requirements

• Git — to download and manage this repository
• Claude Code — the AI tool that reads these files
• A text editor — anything works (VS Code, Notepad, TextEdit, Sublime, vim)
• Rust toolchain (cargo) for first-time local binary builds (lib/)
• Windows: Works natively on Windows 10+. make recipes are POSIX-style; use WSL/Git Bash for make install, or use the PowerShell fallback in INSTALL.md.

License

EUPL 1.2