Files
phronesis/CONTRIBUTING.md
nvaldez ed3d21fd54 feat v0.3.0: MEMORIES.md template in every skill, add-only install/update policy
- 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>
2026-11-19 11:35:48 +01:00

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

  1. Create a directory named after the skill: skill/<kebab-case-name>/.

  2. Add skill/<name>/SKILL.md with 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>`
    ---
    
  3. Add skill/<name>/MEMORIES.md: copy the template from 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).

  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.

  6. Run the checks. All of them must pass:

    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). 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.