ed3d21fd54
- every bundled skill ships MEMORIES.md (memory-skill template, name substituted); autotest frontmatter check enforces its presence (SPEC 4.7) - copy_skill: MEMORIES.md is add-only - installed from the bundle when missing, never overwritten, on both install and update; --force does not change this (SPEC 4.7, 6.8, 7.6); uninstall removes it with the directory (SPEC 6.9, sad by design) - FIX bug in --update: it passed the skill directory where the skills root was expected, copying the bundle into skills/<name>/<name>/ and never refreshing the real SKILL.md; now updates the real files and heals the legacy nested directory on the next copy (SPEC 7.7) - tests strengthened to assert file contents, not just output: 84 total, all checks green; e2e-verified via the installed pipx CLI Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# 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/<kebab-case-name>/`.
|
|
2. Add `skill/<name>/SKILL.md` with this front matter:
|
|
|
|
```yaml
|
|
---
|
|
name: <name> # must equal the directory name
|
|
version: x.y.z # semantic, start at 1.0.0
|
|
description: <one line> # what the skill is for
|
|
category: <kebab> # lowercase label, used by `phronesis <category>`
|
|
---
|
|
```
|
|
|
|
3. Add `skill/<name>/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 <name>`.
|
|
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 <check>` 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<x.y.z> -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).
|