Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (76 loc) · 2.91 KB

CONTRIBUTING.md

File metadata and controls

106 lines (76 loc) · 2.91 KB
Raw

Contributing

Welcome! Whether you are fixing a typo, adding a test, reporting a bug, writing a new skill, or proposing a feature, your help makes spellbook better for everyone.

Development Setup

git clone https://github.com/axiomantic/spellbook.git
cd spellbook
uv pip install -e ".[dev,test,tts]"

Install pre-commit hooks:

uvx pre-commit install

Running Tests

# Run the full suite
uv run pytest tests/ -x --timeout=30

# Run a specific test file
uv run pytest tests/test_specific_file.py -x

# Run linting
uv run ruff check .

A passing run shows something like X passed with exit code 0.

Adding a Skill

  1. Create skills/<your-skill-name>/SKILL.md with YAML frontmatter: 
    ---
name: your-skill-name
description: "Use when [trigger conditions]. Triggers: 'phrase1', 'phrase2'."
---
  2. Write the skill body following existing skills as examples
  3. Run python3 scripts/generate_docs.py to generate the docs page
  4. Pre-commit hooks will validate the schema and check that the docs mirror is current

Adding a Command

  1. Create commands/<your-command-name>.md with YAML frontmatter: 
    ---
description: "Brief description of the command"
---
  2. Run python3 scripts/generate_docs.py to generate the docs page and update the index

Code Style

This project uses Ruff for Python linting and formatting. Pre-commit hooks run these automatically. To run manually:

uv run ruff check .
uv run ruff format .

Submitting a Pull Request

  1. Fork the repository and create a branch from main
  2. Make your changes and add tests if adding functionality
  3. Run the test suite and linter locally
  4. Verify the installer works: uv run install.py --dry-run
  5. Open a pull request with a clear description of what you changed and why

We aim to review pull requests within 5 business days. If you have not heard back, feel free to leave a comment on the PR.

Types of Contributions

Code is not the only way to contribute. We welcome:

  • Bug reports and feature requests via issue templates
  • New skills and commands for common development workflows
  • Documentation improvements and typo fixes
  • Test coverage additions
  • Translations of the README

Pre-commit Hooks

Apart from doctoc, pre-commit hooks check files rather than rewrite them. If a hook fails:

  1. Read the output for the command it tells you to run -- a stale docs mirror reports Run: python3 scripts/generate_docs.py
  2. Run that command, then stage the regenerated files with git add
  3. Commit again

This is normal and expected when adding new skills or commands.

Communication

Thank you for contributing!