mthds-pkg

name	mthds-pkg
description	Manage MTHDS packages — initialize, configure exports, list, and validate. Use when user says "init package", "set up METHODS.toml", "manage packages", "mthds init", "validate package", "list package", or wants to manage MTHDS package manifests.
min_mthds_version	0.12.1

Manage MTHDS packages

Initialize, configure exports, list, and validate MTHDS packages using the mthds-agent CLI.

Process

Step 0 — Environment Check (mandatory, do this FIRST)

Run this command to check toolchain status:

# Wrapped in `bash -c` so the bash array syntax below works even when the
# session shell is zsh (Codex runs blocks under the user's shell).
bash -c '
# Pick the cached env-check from the plugin version with the highest semver.
# Pad each numeric segment to fixed width so lex sort matches semver sort
# (avoids the 0.10 < 0.9 lex-order trap). Sort keys are digits-only by
# construction, so the [[ > ]] compare is locale-independent. Bash 3.2 OK.
_best_f=""; _best_k=""
for f in "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/mthds/*/bin/mthds-env-check; do
  [ -x "$f" ] || continue
  _v="${f%/bin/*}"; _v="${_v##*/}"
  _k=""; IFS=. read -ra _parts <<<"${_v%%[-+]*}"
  for _p in "${_parts[@]}"; do _p=${_p%%[!0-9]*}; _k="${_k}$(printf %06d "${_p:-0}")"; done
  [[ "$_k" > "$_best_k" ]] && { _best_f="$f"; _best_k="$_k"; }
done
[ -n "$_best_f" ] && exec "$_best_f" "0.12.1" --codex
echo "MTHDS_ENV_CHECK_MISSING"
'

Interpret the output:

• MTHDS_AGENT_MISSING → STOP. Do not proceed. Tell the user:

The mthds-agent CLI is required but not installed. Install it with:

npm install -g mthds

Then re-run this skill.

• MTHDS_AGENT_VERSION_UNKNOWN → STOP. The installed mthds-agent returned an unparseable version. Tell the user:

Could not parse the output of mthds-agent --version. Your installation may be corrupt. Reinstall with:

npm install -g mthds@latest

Then re-run this skill.

• MTHDS_AGENT_OUTDATED <installed> <required> → The installed mthds-agent is too old for this plugin. Do not hard-stop. Instead, tell the user their mthds-agent (v<installed>) is older than the required v<required>, then follow the upgrade flow to offer upgrading mthds-agent via npm install -g mthds@latest. After the upgrade flow completes (whether the user upgraded or declined), proceed to Step 1. The upgrade flow's "Not now" and "Never ask" options let users continue with current versions.

• MTHDS_UPDATE_CHECK_FAILED ... → WARN. The update check command failed. Show the error output to the user. Suggest checking network connectivity and mthds-agent installation. Proceed to Step 1 with current versions.

• UPGRADE_AVAILABLE ... → Read upgrade flow and follow the upgrade prompts before continuing to Step 1.

• JUST_UPGRADED ... → Announce what was upgraded to the user, then continue to Step 1.

• UP_TO_DATE ... → Proceed to Step 1. The line is a terse list of verified installed versions (e.g. UP_TO_DATE mthds-agent=0.10.0 plxt=0.4.0 plugin=0.12.0); if you mention the env-check in your preamble acknowledgement, relay the agent and plugin versions you saw. Two "explicit-quiet" variants share the same prefix and are also clean — proceed to Step 1 without warning, and do not relay the quiet state unless the user is troubleshooting:

  • UP_TO_DATE update-check=disabled — the user has turned update-check off via config.
  • UP_TO_DATE update-check=snoozed — the user has an active snooze on the current version key; an upgrade would otherwise be available, but they explicitly asked for quiet.

• No output → WARN. The env-check produced no output at all, which usually means mthds-agent itself is broken or the wrapper script bailed before printing. Tell the user the environment check could not be confirmed, then proceed cautiously to Step 1.

• MTHDS_ENV_CHECK_MISSING → WARN. The env-check script was not found at either expected path. Tell the user the environment check could not run, but proceed to Step 1.

• CODEX_CONFIG_NEEDS_SETUP → Codex's ~/.codex/ is not set up for the mthds plugin, so the bundled .mthds validation hook will not load. When this fires it is the only terminal status the env-check emits — update-check is skipped entirely (not run, not suppressed) because fixing the hook is the prerequisite and update-check's upgrade marker is one-shot; the user re-runs and gets fresh update info next time. The env-check may print one or more #-prefixed diagnostic lines after the status — relay them if present. Resolve this before Step 1:

  1. Preview — run mthds-agent codex apply-config --dry-run and show the user the output. WOULD_APPLY lists the keys it will add under applied; ALREADY_OK means no keys need adding. Either way, relay any warnings entries — those (e.g. read-only sandbox, hooks disabled) need a hand-fix apply-config will not perform. If ALREADY_OK with no warnings, treat as resolved and go to Step 1.
  2. Ask — use AskUserQuestion: "Apply Codex config now?" with options "Apply now" / "Skip".
  3. Apply now — run mthds-agent codex apply-config:
     • APPLIED / ALREADY_OK → tell the user the config is fixed and they must restart Codex for the validation hook to load (it will not load in this session). Relay any warnings — those still need a hand-fix.
     • Error about conflicting keys → show it verbatim; the user must hand-edit ~/.codex/config.toml, then re-run mthds-agent codex apply-config.
     • Error from the sandbox blocking the write to ~/.codex/config.toml → ask the user to run mthds-agent codex apply-config themselves in a terminal, then restart Codex.
  4. Skip — tell the user the validation hook stays off until they run mthds-agent codex apply-config and restart Codex.

  Then proceed to Step 1. This session has no PostToolUse hook. The mthds skills still run mthds-agent validate bundle explicitly, so .mthds files built or edited through a skill are still semantically validated — but the write-time plxt lint/fmt pass depends on the hook and will not run until Codex is restarted.

• Any other output → WARN. The preamble produced unexpected output. Show it to the user verbatim. Proceed to Step 1 cautiously.

Do not write .mthds files manually, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.

No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away. Backend configuration is only needed to run methods with live inference — use /mthds-runner-setup when you're ready.

1. Initialize a package

Create a METHODS.toml manifest:

mthds-agent package init --address <address> --version <version> --description <description> -C <pkg-dir>

Required flags:

Flag	Purpose	Example
--address	Package address (hostname/path format)	github.com/org/repo
--version	Package version (semver)	1.0.0
--description	Package description	"My method package"

Optional flags:

Flag	Purpose	Example
--authors	Comma-separated list of authors	"Alice, Bob"
--license	License identifier	MIT
--name	Method name (2-25 lowercase chars)	my-tool
--display-name	Human-readable display name (max 128 chars)	"My Tool"
--main-pipe	Main pipe code (snake_case)	extract_data
--force	Overwrite existing METHODS.toml	—

2. Configure exports

Exports declare which pipes the package makes available to consumers. They are organized by domain in METHODS.toml:

[exports.restaurant_analysis]
pipes = ["present_restaurant", "extract_menu", "analyze_menu"]

To configure exports:

1. Read the .mthds bundle(s) in the package to find the domain codes and pipe codes defined inside them
2. Edit METHODS.toml to add an [exports.<domain>] section for each domain, listing the pipe codes to export

Rules:

• The main_pipe of each bundle is auto-exported — you do not need to list it unless you want to be explicit
• Concepts are always public and do not need to be listed in exports
• Each [exports.<domain>] section requires a pipes key with a list of pipe code strings

3. List package manifest

Display the current package manifest:

mthds-agent package list -C <pkg-dir>

4. Validate package manifest

Validate the METHODS.toml package manifest:

mthds-agent package validate -C <pkg-dir>

Note: mthds-agent package validate validates the METHODS.toml package manifest. To validate .mthds bundle semantics, use mthds-agent validate bundle (see /mthds-check skill).

The -C option

All mthds-agent package commands accept -C <path> (long: --package-dir) to target a package directory other than the shell's current working directory. This is essential when the agent's CWD differs from the package location.

# From any directory, target a specific package
mthds-agent package init --address github.com/org/repo --version 1.0.0 --description "My package" -C mthds-wip/restaurant_presenter/
mthds-agent package validate -C mthds-wip/restaurant_presenter/

If -C is omitted, commands default to the current working directory.

Common Workflows

Starting a new package:

1. mthds-agent package init --address <address> --version <version> --description <desc> -C <pkg-dir> — create the manifest
2. Read .mthds bundles in the package to extract domain codes and pipe codes
3. Edit METHODS.toml to set the correct [exports.<domain>] sections
4. mthds-agent package validate -C <pkg-dir> — validate the manifest

Reference

• Error Handling — read when CLI returns an error to determine recovery
• MTHDS Agent Guide — read for CLI command syntax or output format details