SPB Git

Repository Public License

skill-development.md 5.6 KB 112 lines markdown

1<!--2ORIX OS Automation3File: docs/skills/skill-development.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Writing a skill89A skill is a small local program that becomes a tool named `skill.<name>`. It runs as a separate, confined10process. It can be written by you, imported from a folder, or proposed by an agent; in every case it is first a11**draft** that is analysed and tested, and it is installed only after you approve it.1213## Package1415```16my-skill/17├── skill.json      manifest18└── main.py         entry file (Python or Bash)19```2021`skill.json`:2223```json24{25  "id": "skill.wordCount",26  "name": "Word count",27  "version": "1.0.0",28  "summary": "Counts the words and lines of a text file.",29  "runtime": "python",30  "entry": "main.py",31  "inputSchema": { "type": "object", "properties": { "path": { "type": "string" } }, "required": ["path"], "additionalProperties": false },32  "outputSchema": { "type": "object", "properties": { "words": { "type": "integer" }, "lines": { "type": "integer" } }, "required": ["words", "lines"] },33  "permissions": { "fileRead": ["$input.path"], "fileWrite": [], "network": [] },34  "timeoutSeconds": 30,35  "author": "you",36  "tests": [37    { "name": "three words", "input": { "path": "$fixture/a.txt" }, "files": { "a.txt": "one two three\n" }, "expectOutput": { "words": 3, "lines": 1 } }38  ],39  "checksums": { "main.py": "<sha-256 of the file>" }40}41```4243- `id` must be `skill.` followed by a camelCase name. A skill cannot take the name of a built-in tool.44- `version` is `major.minor.patch`. Installed content under a version number can never change; raise the version.45- `runtime` is `python` (the system `python3`, standard library, isolated mode) or `bash`.46- `checksums` lists every file except `skill.json`. A file that is missing, extra or different makes the package47  invalid. Symbolic links are refused. (Drafts created in the app or by an agent get their checksums computed for you.)4849## Protocol5051The process receives the input object as JSON on standard input and prints one JSON object on standard output.52A non-zero exit status is a failure; standard error is kept for the error message. The environment contains53`ORIX_SKILL_ID` and `ORIX_ARTIFACTS_DIR` (a folder the skill may always write to).5455```python56import json, sys57data = json.load(sys.stdin)58text = open(data["path"], encoding="utf-8").read()59print(json.dumps({"words": len(text.split()), "lines": text.count("\n")}))60```6162## Permissions6364| Entry | Meaning |65|---|---|66| `fileRead`, `fileWrite` | Absolute paths, `~/…` paths, or `$input.<field>`: the path the caller passes in that input field |67| `network` | Host names. Empty means the process runs with networking denied |6869The tier is derived, not chosen: no write and no network → tier 0; a write location → tier 1; a network host →70tier 2. Protected locations (Keychains, `~/.ssh`, …) are refused in the manifest.7172Each call needs the `skill` capability for that skill, the script runtime, and the concrete paths and hosts73resolved from its arguments. Declaring a permission does not grant it: the policy engine still decides per call.7475At run time the Seatbelt profile allows writes only to the resolved write paths and the artifacts folder, and76network only when hosts are declared. Reads are limited by policy on the declared paths and by the profile's77denial of credential stores; the profile does not otherwise restrict reads.7879## Tests8081Every skill needs at least one test. Each test runs in a fresh scratch folder containing its `files`; `$fixture`82in the input is replaced by that folder. Tests always run with networking denied and may only touch their scratch83folder. A test passes when the status, every `expectOutput` path and every `expectFiles` entry match.8485## Review, install, roll back86871. **Propose**: Skills › New skill, Skills › Import, the Code Studio "Save as skill", or an agent calling88   `skills.propose`. The draft is analysed and its tests are run.892. **Review** the draft in Skills: source, requested permissions, findings, test results.903. **Install** (the user's action; an agent calling `skills.install` triggers an approval that shows the same91   summary). Drafts with a blocking finding, a failing test or no test cannot be installed.924. Installed versions are kept. **Roll back** makes the previous version current; **Disable** removes the tool93   without deleting it; **Uninstall** deletes it.9495Before every run the package is re-verified against its checksums. A skill that changed on disk does not run.9697## Security review checklist9899- [ ] The summary says what the skill does, and the source does only that.100- [ ] Every path the source touches comes from a declared permission; none is built from unrelated input.101- [ ] No network use unless hosts are declared, and the hosts are the ones you expect.102- [ ] No `eval`, `exec`, dynamic import or decoding of embedded code.103- [ ] No reference to credential stores, `sudo`, `osascript`, `launchctl` or other system control.104- [ ] Subprocess use is explained by the task and takes an argument list, not a shell string.105- [ ] Input from files or the caller is treated as data (no shell interpolation, no path concatenation without checks).106- [ ] The tests cover the failure cases you care about, not just the happy path.107- [ ] The output schema matches what the code prints.108109The analyser checks several of these mechanically and reports findings as `info`, `warning` or `blocker`. It is110a reading aid: it can be evaded by code written to evade it. The sandbox and the policy engine are what bound a111skill, which is why undeclared writes and network use fail at run time even when the analyser misses them.112
Files main
Menu

Theme