# Package Agent Skill

> Review and publish an Agent Skill through Agent Plugin Forge from any workspace, or package an MCP server while developing inside a Forge checkout. Use when a user asks to add, copy, organize, bundle, check, or publish a skill, MCP server, or Agent Plugin for VS Code, Copilot, or Codex.

- Skill: `miguelelgallo/package-agent-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add miguelelgallo/package-agent-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/miguelelgallo/package-agent-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MiguelElGallo (https://skillmd.com/u/miguelelgallo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/miguelelgallo/package-agent-skill

---


# Package an Agent Skill

Use `uv run forge` as the deterministic writer and validator. Portable packages under `plugins/` are authoritative. Do not hand-edit generated marketplaces.

For Agent Skill publication when the current workspace is not Agent Plugin Forge, read [references/publish.md](references/publish.md) and bootstrap a disposable, current checkout. The user does not need to clone the repository manually. For a mirror, private repository, persistent checkout, or GitHub Enterprise Server, also read [references/private-github.md](references/private-github.md).

## Intake

Inspect the source without executing scripts or hooks. Forge accepts a skill directory, a lone `SKILL.md`, or an existing Agent Plugin. For a multi-skill plugin, identify the one immediate skill to import with `--source-skill`.

Remote sources must be resolved to an immutable revision and staged locally before import. The forge does not fetch URLs.

Resolve these fields from evidence and ask only for values still materially unknown:

- destination plugin; default to one skill per new plugin and bundle only when explicitly requested;
- selected source skill when a source plugin contains several;
- category for a new plugin only;
- new plugin version, description, and author, or a higher bundle version;
- canonical origin, immutable revision, source subpath, SPDX license, and local license evidence.

Read [references/intake.md](references/intake.md) for remote sources, bundles, multiple source skills, or unclear license and provenance.

## Review checkpoint

Split publication into two phases. An initial request to publish authorizes the review phase only.

1. From clean, current `main`, create `skill/<plugin>/<skill>` with `uv run forge branch --plugin NAME --skill NAME`.
2. Run `uv run forge import ...` without `--apply` and review the printed plan plus every instruction, script, asset, license, and destination.
3. If the source is structurally invalid, stop with the exact diagnostic. Normalize it in a separate reviewed source change; never silently rewrite imported `SKILL.md`.
4. Report the exact plan hash and the actions publication would perform, then stop for explicit approval.

After approval of that exact plan:

1. Repeat the same command with `--apply --expected-sha256 HASH`.
2. Run `uv run forge generate` and `uv run forge check`.
3. Run `uv run ruff check .`, `uv run ruff format --check .`, `uv run ty check`, `uv run pytest`, and `uv run zensical build --clean --strict`.
4. Review the complete diff. Commit, push, and open a pull request only when those external actions were included in the approval. Merge only when separately authorized and the exact reviewed head has green required checks.

MCP and other plugin-wide changes are a Forge contributor workflow; they do not use the hash-bound `forge import` plan. Work only inside a Forge checkout, use `uv run forge plugin-branch --plugin NAME --topic TOPIC`, bump the plugin version, review all runtime files and modes, and validate root `mcp.json`. Do not claim the installed two-phase Skill workflow can publish an MCP-only package. Use `forge/<topic>` only for forge tooling, schemas, CI, or documentation.

## Invariants

- Portable discovery is fixed: root `plugin.json`, immediate `skills/<name>/SKILL.md`, and optional root `mcp.json`.
- Packages may be skill-only, MCP-only, or mixed. Category remains catalog taxonomy, never directory nesting.
- Bundle imports inherit category and require a higher semantic version.
- Imported skill content remains byte-identical with executable modes bound by the plan. Forge metadata stays outside the copied tree in `provenance/`.
- Import copies content without executing it. Treat instructions, scripts, and MCP runtimes as untrusted until reviewed.
- `.github/plugin/marketplace.json` and `.agents/plugins/marketplace.json` are generated outputs; both point to the portable packages.