# Contributing to phronesis A **skill** is one directory under `skill/` containing a single `SKILL.md` file. It must be self-contained: anyone (or any agent) reading only that file should be able to follow the skill. ## Adding a skill 1. Create a directory named after the skill: `skill//`. 2. Add `skill//SKILL.md` with this front matter: ```yaml --- name: # must equal the directory name version: x.y.z # semantic, start at 1.0.0 description: # what the skill is for category: # lowercase label, used by `phronesis ` --- ``` 3. Add `skill//MEMORIES.md`: copy the template from [skill/memory/MEMORIES.md](./skill/memory/MEMORIES.md) and substitute the skill's name for `SKILL_NAME`. It is the starting memory the installed skill uses; installs add it when missing and never overwrite it ([SPEC.md items 6.8, 6.9](./SPEC.md)). 4. Write the instructions below the front matter. Cover identity, rules, workflow, and examples; avoid references that only make sense inside your machine. 5. Add the skill to the table in [README.md](./README.md). 6. Run the checks. All of them must pass: ```bash python -m pip install -r requirements.txt python -m pip install -e . python autotest.py ``` 7. Commit with a semantic message, e.g. `feat: add skill `. A new category is announced to users the moment the skill is bundled, since `phronesis` lists it live. ## Changing a skill - Bump the `version` in the front matter for every change: patch for fixes, minor for additions, major for breaking changes. - Keep `SKILL.md` the only required file; support files are allowed but must stay inside the skill's directory. ## Check failures `autotest.py ` runs one check; without arguments it runs all: - `sanity` — LF line endings, no private keys, file size limit - `python_syntax` — `.py` files parse - `pycodestyle` — PEP 8 on `.py` files - `shellcheck` — shell scripts lint clean - `frontmatter` — YAML header valid, `name`, `version`, and `category` correct - `markdown` — markdownlint (`md013` line length and `md033` inline HTML are ignored) - `pytest` — the suite in `test/`, coverage floor 75 percent ## Style - KISS/YAGNI: a skill that fits in one screen beats a manual. - Plain, imperative sentences. Lists over prose where order matters. - Test what you preach: a TDD skill is itself written cleanly. ## Releasing - Bump `version` in `pyproject.toml`, commit, then tag the release: `git tag -a v -m "..."` and move the `stable`/`latest` roller tags (`git tag -f ...`, `git push -f origin stable latest`). - `python publish.py` guards, builds, and twine-checks exactly the tagged version; `python publish.py --upload` publishes it ([SPEC.md section 12](./SPEC.md)). A published version is immutable: any change, even to the README, is a new version. ## License By contributing you agree your work is released under the [MIT license](./LICENSE).