Skip to main content

Contribute to SkillFlaw

SkillFlaw welcomes contributions across code, documentation, tests, templates, and developer tooling.

For day-to-day repository commands, see Local development deployment and Makefile command reference.

Repository overview​

SkillFlaw has two main application services:

  • Frontend: a React/TypeScript application
  • Backend: a Python/FastAPI service

During local development, the frontend and backend usually run separately:

  • frontend dev server: http://localhost:3000
  • backend API server: http://localhost:7860

When you run the built application through the backend, the frontend is served by the backend on port 7860 by default.

Clone your fork​

  1. Fork the SkillFlaw GitHub repository.
  2. Add your fork as a remote:

_10
git remote add FORK_NAME https://github.com/GIT_USERNAME/skillflaw.git

Replace:

  • FORK_NAME: a name for your fork remote
  • GIT_USERNAME: your GitHub username

Run SkillFlaw from source​

Use this mode if you want to run the built application from the repository without a frontend hot-reload workflow.

macOS / Linux​

From the repository root, run:


_10
make run_cli

This installs dependencies as needed, builds the frontend, and starts the application.

Windows​

You can use the included scripts under scripts/windows/:

  • build_and_run.bat
  • build_and_run.ps1

Or run the steps manually:


_10
cd src/frontend
_10
npm install
_10
npm run build

Then start the backend:


_10
uv run skillflaw run

The built application is served at http://localhost:7860.

Set up a development environment​

Use this mode when you want hot reload for active development.

macOS / Linux​

  1. Initialize the workspace:

_10
make init

  1. Run backend and frontend in separate terminals:

_10
make backend


_10
make frontend

  1. Optional: if you are editing docs too, run the docs site in another terminal:

_10
make docs

  1. Validate your changes before pushing:

_10
make lint
_10
make format
_10
make unit_tests

If you need the full test suite:


_10
make tests

Windows​

Since Windows does not include make by default, run the frontend and backend directly:


_10
cd src/frontend
_10
npm install
_10
npm run start

In another terminal:


_10
uv run skillflaw run --backend-only

Troubleshoot frontend build issues​

If you encounter stale frontend build artifacts, run:


_10
make run_clic

This forces a clean rebuild of the frontend assets before launching the app.

Contribute documentation​

The docs site uses Docusaurus.

  1. Change to the docs workspace:

_10
cd docs

  1. Install docs dependencies and start the local docs site:

_10
npm install
_10
npm run start

  1. Edit source content in these directories:
  • docs/docs
  • docs/i18n/zh-CN/docusaurus-plugin-content-docs/current
  1. Navigation is defined in:

_10
docs/sidebars.js

  1. Before creating a PR, run a production build to catch broken links and MDX issues:

_10
npm run build

Additional contribution guides​

Open a pull request​

  1. Open a pull request against main.
  2. Use a clear, focused title. Conventional prefixes such as feat: and fix: are recommended.
  3. In the PR description, clearly explain what changed, why it changed, and any migration or testing notes.
  4. Keep the PR focused on one primary problem when practical.

SkillFlaw maintainers will review your pull request and may request updates before merge.