Part IV — Automation and extension

This part covers Chapters 14–19: four automation capabilities — the skill system, subtasks and background execution, plan and todo, and history compaction — plus two extension avenues: plugins and companion messaging.

14. The skill system

A skill is a small package of prompt template + metadata that gives the assistant domain-expert capability. AVL Code's skill system follows the mainstream community format, so you can reuse the ecosystem.

14.1 Three layers

Workspace overrides global; convenient when projects need a different take on a skill of the same name.

Directories scanned inside a workspace (on a name clash, lower rows override higher ones):

Earlier releases only scanned the last three, so a skill repo dropped into skills/ "just never showed up". That convention is now official.

Skills on remote workspaces work too: a skill on an SSH / remote workspace is snapshotted in full to a private temporary directory on your machine first, and parsing, verification and rendering all happen against that immutable snapshot — once it passes the check, later changes on the remote can't influence that invocation, and tampering simply makes verification fail. The snapshot inherits every local guardrail (symlinks and non-regular files refused, 256 files per directory, 4 MB per file, 16 MB total, depth 16, and a size change during copying is an outright refusal). ${SKILL_DIR} inside a skill points at the real directory (a workspace-relative path on the remote), so the AI can still read the accompanying resources.

When a skill isn't listed, you're told why: the skill listing now carries the hidden skills and the reason each one is hidden (unsigned / verification failed / parse failure / snapshot failure) plus the current signature policy; invoking a skill by a name that wasn't listed also returns the precise reason instead of just "not found". That puts an end to "the AI searches the whole repo for skills and reaches the wrong conclusion".

Built-in skills (ready to use): the app ships with built-in skills (e.g. an AI-guided skill-creator that helps you create and refine your own skills). Built-in skills are materialized automatically on startup and any content drift is overwritten to keep them consistent; via build-time signing + a built-in signature anchor, they pass even under a strict signing policy. Settings → Skills tags them with a "Built-in" badge to distinguish them from your own and third-party skills.

Agent Skills compatibility hardened: improved compatibility with Agent Skills (agentskills.io) — better cross-client skill discovery and parsing tolerance, plus tool-name translation mapping, so skills from different sources and naming conventions are recognized and called correctly.

14.2 Two ways to trigger

• User-triggered: /skill-name arg1 arg2 in the input box — rendered and injected into the next turn.
• Assistant-triggered: the assistant calls it, result is fed back as a tool response.

More proactive skill matching: the system prompt now includes the catalogue of currently available skills, and the guidance "match a fitting skill by purpose before acting" is reinforced. The AI is more likely to actively pick the right skill instead of doing the work the hard way or reinventing the wheel.

14.3 Skill structure

Each skill is a folder with a Markdown file whose:

• Frontmatter: name, purpose, argument hints, allowed tools, applicable modes.
• Body: prompt template with parameter substitution and small shell preprocessing.

14.4 Write a skill

Here's a minimal conceptual example (exact syntax per the official template):

name: code-review
description: Do a serious review of a piece of code; list issues and improvements
argument-hint: <file path>
allowed-tools: [file read, content search]
work-modes: [plan, assess]
---
Review $1 with focus on:
- edge cases and error handling
- naming and readability
- consistency with the rest of the project

Put this in <workspace>/.config/skills/code-review/ and /code-review src/utils/format.ts triggers it.

14.5 Signing and verification

For team distribution, GM signature verification is recommended. AVL Code ships a built-in signing tool that generates keys, self-signs certificates, signs the whole skill folder and auto-verifies at load — a failed signature refuses execution. This guarantees skills picked up from email or a network drive can't carry malware.

Unified signing-verification policy switch: the signing policy and trust store are now consolidated on the standalone Settings → Skill/Plugin Signatures tab (Security group); one toggle governs both skills and plugins — flipping to "Skip" allows installing unsigned skills and plugins; toggling auto-heals legacy inconsistent state.

Trust store applies as soon as you drop certs in: the trust store supports manual / automatic reload and direct root-certificate (PEM) import — a dropped-in certificate takes effect immediately, no app restart needed.

"Unverifiable provenance" is your call: with the policy at warn, a skill / plugin whose provenance can't be verified now pops a confirmation and lets you decide whether to let it through, while a package with evidence of tampering is still hard-blocked. Rejections and import failures surface the specific reason, not a generic error.

The execution path agrees with the UI: the actual execution path for skills now follows the signature policy you chose in Settings (it used to be pinned to the strictest strict, which produced phantom capabilities — the system prompt said a skill was available while the actual invocation refused it). Policy changes take effect immediately, no restart. The semantics: under warn an unsigned skill is let through, but a skill that carries a signature which fails verification (suspected tampering) is still refused; and if the policy file is missing, unreadable or holds an invalid value, the strictest strict applies.

14.6 Debugging

Settings → Skills → Debugger:

• Template preview (the prompt after substitution).
• Shell-preprocess output.
• Frontmatter validation.
• Applicable-modes check.

14.6.1 Pre-publish self-check: market.check

A new built-in read-only tool market.check validates a local skill / plugin directory against the AVL Code app store's (zMarket's) publishing contract, reporting pass / fail + reasons + what's missing (name slug, strict-semver version, source form, capability declaration, archive safety, etc.). It is local, deterministic, offline — no network, no submission. Run it after creating / editing a skill, before publishing, and fill in per the report.

• Params: path (required, the directory's relative path, e.g. .avlcode/skills/my-skill), kind? (skill / plugin / mcp / provider, auto-detected), version?, source?, manifest?.
• Note: a .skill-sign signature is ≠ zMarket acceptance; this tool only checks the publishing-contract shape, not a runtime security audit.

14.7 Team sharing

Once your skills live in a team repo, new members just drop the folder into the workspace's designated path. Combined with signing, this forms an "internal skill marketplace".