Claude Code instructions for Agentbook

Before working in any directory, always read the AGENTS.md file located in that directory (if one exists) for directory-specific conventions and constraints.

Key AGENTS.md locations in this repository:

/AGENTS.md – top-level contributor notes (link checker usage, CI info).
.github/workflows/AGENTS.md – workflow authoring rules, label lifecycle, and the prohibition on editing *.lock.yml files by hand.

Project overview

Agentbook is a living, self-maintaining book about agentic workflows, agent orchestration, agentic scaffolding, and skills/tools management. It practices what it teaches: community suggestions filed as GitHub issues are processed by a multi-agent pipeline (GitHub Agentic Workflows) that triages, researches, discusses, writes content, and closes issues automatically.

The site is published as a Jekyll-based GitHub Pages site and as a generated PDF.

Technology stack

Layer	Technology
Static site generator	Jekyll (GitHub Pages default, Jekyll 3.x)
Theme	`jekyll-theme-minimal`
Markdown parser	Kramdown with GFM
Syntax highlighting	Rouge
PDF generation	Pandoc + LaTeX (`xelatex`) via `pandoc/latex:latest` container
CI/CD	GitHub Actions
Agentic workflows	GitHub Agentic Workflows (GH-AW) with `gh aw` CLI extension
Hosting	GitHub Pages
Agent engines	Copilot, Claude
Link validation	Python 3 script (`scripts/check-links.py`)

Repository structure

agentbook/
├── book/
│   ├── chapters/              # Book content (13 numbered .md files)
│   ├── pandoc/latex-header.tex
│   ├── agentic-workflows-book.pdf
│   ├── README.md
│   └── index.md               # Jekyll page that assembles chapters
├── blog/index.md              # Blog listing page
├── _posts/                    # Blog posts (YYYY-MM-DD-title.md)
├── _includes/                 # Jekyll includes (head-custom.html, book-toc.html)
├── assets/css/style.scss      # Custom styling
├── scripts/
│   ├── check-links.py         # Internal/external link validation
│   └── build-combined-md.sh   # Combines chapters into single .md for PDF
├── .github/
│   ├── agents/                # GH-AW agent definitions (7 agents) — DO NOT MODIFY
│   ├── workflows/             # GitHub Actions workflows + GH-AW source/lock files
│   │   ├── AGENTS.md          # Workflow authoring rules (read this first)
│   │   ├── pages.yml          # Deploy to GitHub Pages
│   │   ├── build-pdf.yml      # Generate PDF via Pandoc
│   │   ├── check-links.yml    # Internal link check on PR/push
│   │   ├── check-external-links.yml  # Scheduled external link check
│   │   ├── compile-workflows.yml     # Verify .lock.yml files are up to date
│   │   ├── issue-*.md         # GH-AW workflow sources (6 files)
│   │   └── issue-*.lock.yml   # Compiled GH-AW workflows (6 files) — DO NOT EDIT
│   ├── ISSUE_TEMPLATE/suggestion.yml
│   └── copilot-instructions.md
├── _config.yml                # Jekyll configuration
├── index.md                   # Site homepage
├── AGENTS.md                  # Top-level contributor notes
├── CLAUDE.md                  # This file
├── SETUP.md                   # Setup and deployment guide
├── WORKFLOW_PLAYBOOK.md       # GH-AW lifecycle reference
├── README.md                  # Project README
└── LICENSE                    # MIT

Book chapters

Chapters live in book/chapters/ and are numbered with a three-digit prefix for sort order:

File	Topic
`000-front-matter.md`	Front matter
`010-introduction.md`	Introduction to Agentic Workflows
`015-language-models.md`	Language Models
`020-orchestration.md`	Agent Orchestration
`030-scaffolding.md`	Agentic Scaffolding
`040-skills-tools.md`	Skills and Tools Management
`050-discovery-imports.md`	Discovery and Imports
`060-gh-agentic-workflows.md`	GitHub Agentic Workflows
`070-github-agents.md`	GitHub Agents
`080-agents-for-coding.md`	Agents for Coding
`090-agents-for-math-physics.md`	Agents for Math & Physics
`100-failure-modes-testing-fixes.md`	Failure Modes, Testing, and Fixes
`800-future-developments.md`	Future Developments
`990-bibliography.md`	Bibliography

Critical rules

NEVER do these

Do not modify .github/agents/ files — these are agent definitions managed by the GH-AW system.
Do not edit *.lock.yml files by hand — they are generated by gh aw compile from the corresponding *.md source in .github/workflows/. Always edit the .md source and recompile.
Do not commit secrets or credentials.
Do not add binary files to the repository (the one exception is book/agentic-workflows-book.pdf, managed by the build-pdf workflow).
Do not break the Jekyll build — verify with bundle exec jekyll build when possible.
Do not change chapter numbering without updating all cross-references.
Do not add content outside project scope (agentic workflows, orchestration, scaffolding, skills/tools, GitHub agent integrations).

ALWAYS do these

Read the relevant AGENTS.md before working in any directory.

Run internal link checks after changing files under book/:

python3 scripts/check-links.py --root book --mode internal

Validate the Jekyll build when possible:
```
bundle exec jekyll build
```
Keep changes focused and atomic — one logical change per commit/PR.
Maintain existing writing style — educational, practical, professional but accessible.
Include YAML frontmatter for any new blog posts (layout: post, title, date).

Validation and testing

Link checking (offline-safe)

python3 scripts/check-links.py --root book --mode internal

This validates all internal markdown links and anchors within book/. It runs in CI on every push/PR that touches book/**/*.md.

External link checking (requires internet)

python3 scripts/check-links.py --root book --mode external

This validates HTTP/HTTPS links. Runs on a schedule in CI (1st and 16th of each month).

Jekyll build

bundle exec jekyll build    # Build and check for errors
bundle exec jekyll serve    # Serve locally at http://localhost:4000

PDF generation

bash scripts/build-combined-md.sh           # Produces combined.md
pandoc combined.md -o book.pdf --pdf-engine=xelatex -H book/pandoc/latex-header.tex

PDF builds run automatically in CI when book/**/*.md files change.

GH-AW workflow compilation

Agentic workflow sources (.github/workflows/issue-*.md) must be compiled to lock files (.lock.yml) using the gh aw CLI extension. The compile-workflows.yml CI workflow verifies lock files are current.

To compile:

# Install gh-aw extension
gh extension install github/gh-aw

# Compile all workflows
gh aw compile

# Compile a specific workflow
gh aw compile <workflow-id>

# Debug compilation errors
gh aw compile <workflow-id> --json

If gh extension install fails without GH_TOKEN, use the install script:

curl -sLO https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh
bash install-gh-aw.sh
gh aw version

Issue lifecycle labels

Issues progress through these labels in order (unless rejected/closed early):

acknowledged — intake ACK has run
triaged-fast-track or triaged-for-research — routing decision
researched-waiting-opinions — research pass complete
phase-1-complete then phase-2-complete — long-task phases complete
assigned — final assignment and closure

Any agent may reject at any stage by posting rationale, adding rejected, and closing the issue.

CI workflows summary

Workflow	Trigger	Purpose
`pages.yml`	Push to main, manual	Deploy Jekyll site to GitHub Pages
`build-pdf.yml`	Changes to `book/*/.md`, manual	Generate PDF, create PR, attach to releases
`check-links.yml`	Changes to `book/*/.md` or `scripts/check-links.py`	Internal link validation
`check-external-links.yml`	Schedule (bimonthly), manual	External URL validation
`compile-workflows.yml`	Changes to `.github/workflows/*.md`	Verify GH-AW lock files are current
`issue-intake-ack.yml`	`issues.opened`	Acknowledge issue and dispatch routing workflow
`issue-routing-decision.lock.yml`	`workflow_dispatch`	Agentic routing decision (`triaged-fast-track` or `triaged-for-research`)
`issue-fast-track-close.lock.yml`	Label `triaged-fast-track`	Implement small changes via PR
`issue-research-pass.lock.yml`	Label `triaged-for-research`	Research and analyze suggestions
`issue-phase1-dispatch.yml`	Label `researched-waiting-opinions`	Select phase 1 engine and dispatch run
`issue-phase2-dispatch.yml`	Label `phase-1-complete`	Select phase 2 engine and dispatch run
`issue-phase1-*.lock.yml`	`workflow_dispatch`	Post phase 1 long-task analysis
`issue-phase2-*.lock.yml`	`workflow_dispatch`	Post phase 2 long-task delivery plan
`issue-assignment-close.lock.yml`	Label `phase-2-complete`	Final assignment and closure

Coding conventions

Markdown content

Use GitHub Flavored Markdown (GFM)
Code fences with language specifiers ( python `, `yaml , etc.)
Heading hierarchy: # for chapter titles, ## for sections, ### for subsections
Keep paragraphs concise; use bullet/numbered lists for clarity

File naming

Book chapters: NNN-descriptive-name.md (three-digit prefix, e.g., 040-skills-tools.md)
Blog posts: YYYY-MM-DD-title.md
Agent files: issue-{purpose}.md
Workflows: descriptive-name.yml

Code examples

Primary language: Python for agent and workflow examples
Secondary language: TypeScript/JavaScript for GitHub integration examples
Include comments explaining the code
Prefer clear, educational code over terse patterns

YAML

2-space indentation (no tabs)
Minimal required permissions in workflows (principle of least privilege)

Key reference documents

Document	Purpose
`README.md`	Project overview, contribution guide, local dev setup
`SETUP.md`	GitHub Pages setup, permissions, labels, troubleshooting
`WORKFLOW_PLAYBOOK.md`	GH-AW lifecycle diagram, label progression, routing rules
`.github/copilot-instructions.md`	Copilot-specific instructions (overlaps with this file)
`.github/workflows/AGENTS.md`	Workflow authoring rules, `gh aw` usage, label lifecycle