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