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 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:

---
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 as an example.

For catalog changes, validate once from the repository root:

python3 bin/validate-skills

After adding, removing, or moving a skill, preview and sync:

./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: 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. 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:

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 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:

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.

4.3 KiB Raw Blame History