- 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>
3.0 KiB
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
-
Create a directory named after the skill:
skill/<kebab-case-name>/. -
Add
skill/<name>/SKILL.mdwith this front matter:--- 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>` --- -
Add
skill/<name>/MEMORIES.md: copy the template from skill/memory/MEMORIES.md and substitute the skill's name forSKILL_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). -
Write the instructions below the front matter. Cover identity, rules, workflow, and examples; avoid references that only make sense inside your machine.
-
Add the skill to the table in README.md.
-
Run the checks. All of them must pass:
python -m pip install -r requirements.txt python -m pip install -e . python autotest.py -
Commit with a semantic message, e.g.
feat: add skill <name>. A new category is announced to users the moment the skill is bundled, sincephronesislists it live.
Changing a skill
- Bump the
versionin the front matter for every change: patch for fixes, minor for additions, major for breaking changes. - Keep
SKILL.mdthe 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 limitpython_syntax—.pyfiles parsepycodestyle— PEP 8 on.pyfilesshellcheck— shell scripts lint cleanfrontmatter— YAML header valid,name,version, andcategorycorrectmarkdown— markdownlint (md013line length andmd033inline HTML are ignored)pytest— the suite intest/, 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
versioninpyproject.toml, commit, then tag the release:git tag -a v<x.y.z> -m "..."and move thestable/latestroller tags (git tag -f ...,git push -f origin stable latest). python publish.pyguards, builds, and twine-checks exactly the tagged version;python publish.py --uploadpublishes it (SPEC.md section 12). 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.