Files
phronesis/README.md
T
nvaldez e913d0b67f feat v0.2.0: phronesis <skill> --uninstall - remove installed skills
- --uninstall [--project] removes the harness target skill directory
  and drops the matching state entry; --install/--uninstall exclusive
- safety guard (SPEC 6.6): the directory must hold a parseable SKILL.md
  whose front-matter name equals the directory, else refused, exit 2;
  unbundled (retired) skill names can still be removed by name
- SPEC section 6 items 6.6-6.7, section 3 table/3.2, item 8.4 rewritten;
  README command block; 8 new tests (76 total, all checks green)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 11:22:35 +01:00

107 lines
4.6 KiB
Markdown

# phronesis
A chest of skills: a repository of `SKILL.md` instruction packages and
a CLI that lists them and installs them into an agent harness such as
[Vibe](https://mistral.ai).
The name is [phronesis](https://en.wikipedia.org/wiki/Phronesis) —
Aristotle's word for *practical wisdom*: the knowledge a skilled
practitioner has, as opposed to abstract theory (`episteme`).
## Install
```bash
pipx install phronesis # or: pip install phronesis
phronesis # list every bundled skill
```
## Command line
```text
phronesis list every skill
phronesis <category> filter the list
phronesis <skill> show one skill and an install hint
phronesis <skill> --install [--harness <name>] install globally (~/.vibe/skills)
phronesis <skill> --project [--harness <name>] install in the project only (.vibe/skills)
phronesis <skill> --uninstall remove it again (project scope: add --project)
phronesis --update update every installed skill
```
- Already-installed skills prompt before being overwritten; `-f` /
`--force` skips the prompt.
- Installations are recorded in a per-machine state file
(`~/.config/phronesis/installed.json`), which powers `--update`.
- Shell completion via argcomplete; run
`activate-global-python-argcomplete` once after pipx install.
The example table:
```text
Phronesis Version: 0.1.0
skill version category
----------- ------- ----------
python-tdd 1.2.0 development
Minimalist TDD architect for Python work
```
## Layout
```text
phronesis/
├── src/phronesis/ # the CLI package (cli, registry, harnesses, state, ...)
├── test/ # pytest suite
├── skill/ # one directory per skill; ships as package data
│ └── python-tdd/SKILL.md
├── autotest.py # every repo check, single entry point
├── SPEC.md # the full specification (sectionized, citable)
├── README.md, CONTRIBUTING.md, LICENSE
└── pyproject.toml, requirements.txt
```
## Skills
| Skill | Version | Category | Purpose |
| --- | --- | --- | --- |
| [fiona](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/fiona/SKILL.md) | 2.2.0 | productivity | Operate an llm-wiki with the fiona-assistant CLI |
| [memory](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/memory/SKILL.md) | 1.0.1 | productivity | Give a skill its own MEMORIES.md beside its SKILL.md |
| [python-tdd](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/python-tdd/SKILL.md) | 1.2.0 | development | Minimalist TDD architect for Python work |
| [sectionize-markdown](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/sectionize-markdown/SKILL.md) | 1.2.0 | documentation | Number headings and list items so each rule can be cited |
| [specification-writer](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/specification-writer/SKILL.md) | 1.1.0 | documentation | Write structured, maintainable SPEC.md files |
## Checks
`autotest.py` verifies every script and markdown file in the repo:
- **sanity** — LF line endings, no committed private keys, file size limit
- **python_syntax** — every `.py` file parses (`ast.parse`)
- **pycodestyle** — PEP 8 style on every `.py` file
- **shellcheck** — every shell script (`.sh`, `.bash`, or shebang)
- **frontmatter** — every `skill/<name>/SKILL.md` carries a `---` fenced
YAML header with `name`, `version`, `description`, `category`; `name`
matches the directory, `version` is `x.y.z`, `category` is kebab
- **markdown** — markdownlint on every `.md` file, via `pymarkdownlnt`
with front-matter support; `md013` (line length) and `md033` (inline
HTML) are ignored, and md025 treats front-matter `title` keys as
headings off, so skills with a `title` plus one `#` stay clean
- **pytest** — the suite in `test/` with 75 percent coverage floor
Run all checks:
```bash
python -m pip install -r requirements.txt
python -m pip install -e .
python autotest.py # every check
python autotest.py frontmatter # only the named checks
```
## Adding a skill
See [CONTRIBUTING.md](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/CONTRIBUTING.md). The short version: one
directory per skill under `skill/`, everything the agent needs in a
single `SKILL.md`, and `python autotest.py` green before you commit.
## License
[MIT](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/LICENSE)