Contributing

Why Contribute

There are thousands of non-fiction books containing actionable knowledge that AI agents cannot access today. Every book you process through BookForge makes that knowledge available to every agent user.

The model is straightforward: pick a book, run the pipeline, review the output, submit a PR.

Prerequisites

Python 3.12+
The BookForge pipeline installed (pip install bookforge-ai)
A GitHub account
A legally obtained copy of the book you want to process

Step by Step

1. Fork the Repository

Fork bookforge-skills on GitHub and clone your fork locally.

git clone https://github.com/YOUR_USERNAME/clawshelf-skills.git
cd clawshelf-skills

2. Choose a Book

Check the domain list to see which domains need coverage. Look for books that score well on the six skill density dimensions:

Skill Density — contains concrete procedures, not just theory
Digital Actionability — the procedures can be executed by an AI agent
Output Verifiability — you can check whether the skill was applied correctly
Trigger Clarity — obvious when the skill should activate
Reuse Frequency — the skill will come up regularly in real work
Composability — works alongside other skills

Books heavy on narrative or philosophy tend to score low. Books with checklists, frameworks, and step-by-step methods score high.

3. Run the Pipeline

bookforge process path/to/book.pdf --domain=software-architecture

The pipeline runs all 5 stages (Extract, Decompose, Synthesize, Verify, Optimize) and outputs skill packages to output/.

Review the decomposition report to see which sections were selected and which were filtered out. The report shows skill density scores for every section.

4. Review the Output

Check each generated skill for:

Accuracy — does the skill faithfully represent the source material?
Generalization — does it use domain-standard terminology, not author-specific jargon?
Completeness — are there missing steps or undocumented edge cases?
WHY reasoning — does every step explain why it matters?
Progressive disclosure — is the body under 500 lines, with details in references/?

Edit the output if needed. The pipeline produces a strong first draft, but human review catches things automation misses.

5. Submit a PR

Copy the skill packages into the appropriate domain directory in your fork:

cp -r output/architecture-tradeoff-analysis clawshelf-skills/software-architecture/

Commit with a descriptive message:

git add .
git commit -m "feat: add architecture-tradeoff-analysis from Fundamentals of Software Architecture"
git push origin main

Open a pull request against the main repository. Include in the PR description:

Which book you processed
How many skills were generated vs filtered out
Any manual edits you made and why

Quality Standards

Reviewers check every submitted skill against these criteria:

All required SKILL.md sections are present (frontmatter, When to Use, Process, Examples)
Body is under 500 lines
Every process step includes WHY reasoning
At least 2 examples in Scenario/Trigger/Process/Output format
Scripts are functional and tested
No author-specific jargon — domain-standard terms only
Verification tests pass (with-skill vs without-skill comparison)

Review Process

A maintainer will review your PR within a few days. Common feedback:

Descriptions that are too broad (triggering on irrelevant tasks) or too narrow (missing valid triggers)
Steps missing WHY reasoning
Jargon that should be generalized
Skills that overlap significantly with existing ones

Request a Book

Want a specific book processed but don't have time to do it yourself? Open a thread in GitHub Discussions with the book title, author, and which domain it belongs to.

Licensing

Skills (SKILL.md files, references, templates) are licensed under CC-BY-SA 4.0. Anyone can use, share, and adapt them with attribution.
Pipeline code is licensed under MIT. Use it however you want.
Source books are copyrighted by their authors. Never include book text verbatim in skills. Skills distill knowledge into original procedural form.

Contributing

On this page