Moving an Agent Skill Requires More Than Copying SKILL.md

A release-note skill works in one agent and fails in another: the template is missing, a runtime is unavailable, or a dependency installer waits for input. Shared instructions do not make execution environments identical. Check those assumptions before rewriting the prompt.

The Agent Skills specification and script guidance were reread on November 13, 2026. This is a migration design, not a tested comparison of two agent hosts. For the introductory distinction between project rules and skills, see the existing guide.

State dependencies where the host can find them

Consider a skill that turns a public change list into a local release note. Publishing, pushing, and creating remote releases are outside its defined task:

release-note/
├── SKILL.md
├── scripts/render.py
└── assets/release-template.md

Its front matter could describe the environment explicitly:

---
name: release-note
description: Create a local release note from a public change list. Use when drafting release notes before publication.
compatibility: Requires Python 3.11+ and local file access; the render step needs no network.
metadata:
  version: "1.0"
---

This is an illustrative package design. Your team must still supply the script and template. The compatibility field describes requirements; a version in metadata is a maintenance record rather than an enforced runtime lock.

A valid package can still fail to match a request. Check which directory the host discovered, which description it exposed, and whether it loaded the instructions. Copying every reference into SKILL.md is not a targeted fix for discovery failures.

Distinguish package paths from project paths

The bundled template belongs to the skill. The change list and output belong to the user's project. They need not share a working directory.

The specification uses references relative to the skill root. Verify how the destination host resolves them, and make process paths explicit. This unexecuted Bash/Zsh example assumes both absolute paths are already known:

SKILL_DIR="/absolute/path/to/release-note"
PROJECT_DIR="/absolute/path/to/demo-project"
python3 "$SKILL_DIR/scripts/render.py"   --input "$PROJECT_DIR/changes.json"   --template "$SKILL_DIR/assets/release-template.md"   --output "$PROJECT_DIR/release-note.md"

These flags describe the proposed teaching script's interface; they must be implemented. An explicit output location prevents accidental writes into the installed skill directory. Adapt quoting and invocation for other shells rather than treating this as a universal command.

Available dependencies and granted permissions differ

The official script guide recommends explicit prerequisites, pinned tools, concise help, and noninteractive execution. Runtime package launchers may download code even when they leave the project's dependency manifest alone. Network access and execution approval still depend on the environment.

The specification marks allowed-tools as experimental. Host support varies. It cannot create a missing tool or override the host's permission policy. Keep publication authorization separate from permission to draft a local note.

Document credential variable names and retrieval procedures without bundling tokens or private machine configuration. The MCP permissions guide and API key guidance cover related boundaries.

Validate explicit execution before automatic matching

Use the same public input and template on both hosts. Invoke the skill explicitly and check the discovered path, input identity, output location, required sections, missing-dependency behavior, and absence of unauthorized publication.

Scripts should separate structured output from diagnostic messages and return a failing exit code when appropriate. For state-changing operations, provide a preview or dry-run whose actual scope is documented. A reassuring sentence from the model is not a substitute for inspecting the file.

Only after execution works should you test whether natural requests activate the skill. This separates matching problems from runtime failures. A single successful migration does not establish reliability across models or a token saving. The shared governance article explains the standards work; your dependency contract and acceptance record remain local responsibilities.