111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
|
# Authoring and maintenance
|
||
|
|
|
||
|
|
Shared workflows live in `skills/<name>/`; JEV runtime-specific skills remain in
|
||
|
|
JEV. Installed directories link to those sources. Maintain one procedure per
|
||
|
|
workflow and use small aliases when an old name needs to remain callable.
|
||
|
|
|
||
|
|
## Add or edit a skill
|
||
|
|
|
||
|
|
Use [skill-architect](../skills/skill-architect/SKILL.md) for catalog work. A skill
|
||
|
|
needs concrete activation criteria, useful steps, and appropriate completion
|
||
|
|
evidence. There is no required phase structure or length quota.
|
||
|
|
|
||
|
|
Example `SKILL.md` metadata:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
name: example-skill
|
||
|
|
description: >
|
||
|
|
Perform a specific workflow when the user requests its concrete outcome.
|
||
|
|
scope: global
|
||
|
|
---
|
||
|
|
```
|
||
|
|
|
||
|
|
Names use lowercase kebab-case and match the containing directory. Scope values:
|
||
|
|
|
||
|
|
| Scope | Meaning |
|
||
|
|
| --- | --- |
|
||
|
|
| `global` | Reusable workflow; preserve the target repository's conventions. |
|
||
|
|
| `project` | Requires a named project's tooling or layout; explain that dependency. |
|
||
|
|
| `alias` | Explicit compatibility entry point delegating to another skill. |
|
||
|
|
|
||
|
|
Scope is descriptive metadata; a harness must implement its own routing policy.
|
||
|
|
Write optional recipes under `references/` and link them where they help a decision.
|
||
|
|
Keep relative links valid from the source file. Use the
|
||
|
|
[template](../skills/skill-architect/references/sample-skill.md) as an example.
|
||
|
|
|
||
|
|
For catalog changes, validate once from the repository root:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
python3 bin/validate-skills
|
||
|
|
```
|
||
|
|
|
||
|
|
After adding, removing, or moving a skill, preview and sync:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
./sync-skills.sh --dry-run
|
||
|
|
./sync-skills.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Content-only edits already propagate through existing links. Commit according to
|
||
|
|
the user's request and repository/session conventions; these tools do not commit.
|
||
|
|
|
||
|
|
## Workflow rules
|
||
|
|
|
||
|
|
Follow [shared workflow and verification](../protocols/workflow.md): use existing
|
||
|
|
context, preserve user work, and choose checks that can detect a real failure in
|
||
|
|
the changed behavior. Avoid mandatory cross-skill handoffs, repeated confirmation,
|
||
|
|
full suites for prose edits, or automatic spec creation for ordinary bug fixes.
|
||
|
|
|
||
|
|
In an adopted spec workflow, `spec` owns architecture and task definitions, `build`
|
||
|
|
owns task statuses, and `backprop` owns bug records and bug-related invariants.
|
||
|
|
See [the spec format](../skills/spec/references/format.md). A review-only request
|
||
|
|
produces findings without edits or commits.
|
||
|
|
|
||
|
|
## What validation covers
|
||
|
|
|
||
|
|
`bin/validate-skills` checks metadata, matching names, scope, duplicate source
|
||
|
|
names, and local Markdown targets outside fenced examples. It uses Python's
|
||
|
|
standard library and supports this catalog's scalar/block-string YAML subset.
|
||
|
|
It does not verify web links, Markdown anchors, arbitrary YAML schemas, or whether
|
||
|
|
an agent will activate or execute a skill correctly.
|
||
|
|
|
||
|
|
Both tools accept `--global-dir` and `--jev-dir`. Sync additionally accepts
|
||
|
|
repeatable `--target` arguments. Use source overrides consistently when checking
|
||
|
|
a custom installation. Link ownership is inferred from those source roots; it is
|
||
|
|
not recorded in a separate manifest.
|
||
|
|
|
||
|
|
## Verify tool changes
|
||
|
|
|
||
|
|
When sync, validation, or delivery behavior changes, run the relevant regression
|
||
|
|
checks from the repository root:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
python3 -m unittest discover -s tests -v
|
||
|
|
```
|
||
|
|
|
||
|
|
Tests use temporary source catalogs and targets; they do not change installed
|
||
|
|
agent directories. Coverage includes link ownership, stale cleanup, read-only
|
||
|
|
modes, collisions, missing sources, and delivery command generation.
|
||
|
|
|
||
|
|
[Workflow evaluation cases](../tests/workflow-cases.md) are optional fixtures for
|
||
|
|
trigger or policy changes. A behavioral evaluation requires observed agent actions;
|
||
|
|
passing script tests does not prove routing quality. Use real failures to guide
|
||
|
|
small corrections rather than adding more mandatory checks.
|
||
|
|
|
||
|
|
## Delivery helper
|
||
|
|
|
||
|
|
`bin/t3-deliver` prints a quoted `scp` command using this host's Tailscale address.
|
||
|
|
It requires Bash and `realpath`; the receiving Windows machine needs OpenSSH scp
|
||
|
|
with SFTP support and access to the host. It starts no server or transfer.
|
||
|
|
|
||
|
|
To expose it on PATH, link the helper from the repository root:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mkdir -p "$HOME/.local/bin"
|
||
|
|
ln -s "$PWD/bin/t3-deliver" "$HOME/.local/bin/t3-deliver"
|
||
|
|
```
|
||
|
|
|
||
|
|
Inspect an existing destination before replacing it. `sync-skills.sh` installs
|
||
|
|
skill directories, not this executable link. On another host, adapt the address
|
||
|
|
in `bin/t3-deliver` and the delivery skill's host-specific instructions together.
|