1. What a skill is, in thirty seconds

A skill is an integration package: it describes how to use a service or a family of functions. Its entry point is SKILL.md; scripts and reference material may sit beside it. Import is an administrative operation. Metnos turns what the skill declares into executors with explicit names, arguments, capabilities, and provenance.

The file contains a metadata header and a readable body for functions, prerequisites, commands, and examples. The parser turns that material into a structure that can be checked; prose is not treated as permission to expand the system vocabulary or its capabilities.

Metnos can import a skill source: it reads the file, derives a set of executors in its own format, and submits each one to admission checks. Those that pass enter the same catalog as other executors. They become usable once they are also signed, enabled, and not dormant because of a missing dependency. Their manifests continue to record the external origin.

Why Metnos does not execute the skill directly

A SKILL.md file does not carry the signature and contract of a Metnos executor. Importing generates a wrapper, declares capabilities and arguments in a manifest, applies admission checks, and attempts to sign each accepted executor. The wrapper may then call scripts from the package, but it does so through the ordinary Metnos execution path. This makes the granted authority narrower and observable; it does not prove third-party code benign.

2. From the SKILL file to the catalog

The import command starts a sequence of distinct steps. The distinction matters: successful translation is not yet admission to the catalog.

1. Acquire. Metnos resolves the path or URL, obtains the source, and fingerprints the SKILL.md file itself.
2. Parse. The parser extracts metadata, dependencies, scripts, required credential files, and sub-commands with their arguments.
3. Translate. Each sub-command maps to a canonical action_object_qualifier name. The provider qualifies imported executors, and collisions within the skill are rejected.
4. Generate. Controlled templates produce the Python wrapper, TOML manifest, and language state. A language model may propose Italian and English descriptions and one list of affinity phrases; a deterministic fallback is used when it is unavailable. Affinity is not yet separated by language: this is the limitation tracked by the priority AFF-I18N-001 TODO.
5. Admit. The runtime checks binding uniqueness, canonical naming, affinity overlap, routing, and semantic alignment between manifest and code.
6. Sign. Rejected folders are removed. Accepted executors are signed with Ed25519; the loader does not expose one without a valid signature.
7. Register. The outcome enters the import log and, for mappable cases, the persistent routing battery. The executors become visible on the next valid catalog load.

Name and argument translation is procedural for the current source and vocabulary. The whole import does not promise byte-for-byte identical output: provenance contains the import time, descriptions may come from a model, and admission depends on the installed catalog and the available semantic verifier.

The closed vocabulary

Metnos accepts only actions and objects defined by the runtime vocabulary. A skill that speaks of append rows to spreadsheet cannot invent append_rows; it must map to a compatible canonical name. If no semantically correct mapping exists, the sub-command is rejected. Synonyms and skill-specific phrasing therefore cannot introduce new verbs implicitly.

3. Supported sources

A skill can come from three places:

• Local: a SKILL.md file or a directory that contains it. Adjacent scripts/ and references/ are retained with the source.
• agentskills.io: an address of the form agentskills.io/<author>/<skill>; the importer resolves it to the SKILL.md file at the expected repository root.
• Direct GitHub: a full repository URL is cloned with its support files; a raw URL downloads only the named file.

If a skill calls its own scripts, import a complete local directory or the repository rather than the raw file alone. By default, a remote source already in the cache is reused for seven days. Once stale, Metnos fetches it again but does not automatically remove every old cache file; an operator can force a fresh fetch or clear the cache.

4. Generated files and provenance

The source is retained separately from the generated executors. With the default paths, both trees belong to the user who performs the import:

~/.local/share/metnos/skills/google-workspace/
 SKILL.md
 scripts/
 references/

~/.local/share/metnos/executors/skills/google-workspace/
 read_events_google_workspace/
  read_events_google_workspace.py
  manifest.toml
  manifest.lang_state.json
  manifest.toml.sig
 send_messages_google_workspace/
  …

Before signing, each directory contains three generated files: wrapper, manifest, and language state. Signing adds manifest.toml.sig. Scripts and references remain in the source package and are called by the wrapper. The runtime applies sandbox constraints from the contract and declared capabilities, without another per-executor file.

The manifest retains its link to the source:

[provenance]
synthesized       = true
imported_from     = "<skill origin>"
source_version    = "1.1.0"
source_section    = "<section>"
source_subcommand = "calendar list"
imported_at       = "<UTC instant>"
source_sha256     = "<SKILL.md fingerprint>"
importer_version  = "<version>"

Location, provenance, retained source, and audit distinguish an imported executor from one maintained directly in the product. Signature, contract, and execution policy are shared requirements: provenance replaces none of those controls.

What the fingerprints actually cover. source_sha256 identifies SKILL.md. The executor signature protects its manifest and the wrapper code declared by that manifest. Scripts and references copied beside the skill do not currently receive a separate provenance fingerprint, so they must be reviewed as part of the package before import.

5. Translation and admission checks

The pipeline separates translation rejections from admission rejections. The final audit records both categories.

Independent plans can have different outcomes: rejected directories are removed and the others continue. A global binding collision is the exception and rejects the whole import. Options that bypass L2, L5, or L6 are intended for development and CI; using them weakens the evidence and is not equivalent to production certification.

The import report is authoritative for that particular run: it lists translated plans, accepted names, and rejections with reasons. An accepted name alone does not prove that every possible L5 assertion ran, because some patterns explicitly allow a skip.

6. Credentials and dialogs with the user

Importing does not collect credentials. If a provider reports missing authentication during use, the generated wrapper returns decision = "needs_inputs" and preserves the arguments needed to resume the operation.

1. Metnos presents the dialog declared by the manifest in the chat; web chat can open the protected form, while other channels provide directions to reach it.
2. For OAuth, the user supplies the client file and service scope, then completes authorization in the browser.
3. The server exchanges the code and stores the token in the user's encrypted credential store, under ~/.config/metnos/credentials/ by default.
4. If a compatibility provider also requires a file at its own path, the manifest can request a local copy protected with mode 0600.
5. Metnos then resumes the executor with its original arguments.

Credential bindings and values are isolated per user. The manifest declares only the binding name and dialog schema: secrets do not enter the manifest, generated code, or text sent to the planner. The canonical find_credentials, set_credentials, and delete_credentials executors expose metadata, protected writes, and deletion respectively; their planner-facing results contain no plaintext secret values.

7. Google Workspace: a complete example

For the user, an imported skill looks like any other Metnos capability. They might ask, “What appointments are on my work calendar tomorrow?” If Google Workspace has been imported, admitted, enabled, and connected to their account, the catalog can propose the event executor. The same user might ask “Find unread messages from Anna,” “Read the contents of this Drive file,” or “Append these rows to the Expenses sheet.”

Importing is a separate administrative operation. The Google Workspace package included with Metnos also contains the required scripts, so the command uses the complete directory:

metnos-skills import <install-root>/executors/skills/google-workspace

The source declares 24 sub-commands. The current procedural verification proves 24 distinct canonical plans with no translation rejection. Several important semantic distinctions are:

The 24/24 result covers translation, name uniqueness, and manifest generation. It does not justify declaring “24 admitted” in advance: L2 compares the user's catalog, L5 depends on executable checks, and L6 depends on the semantic verifier. The report from that import states how many executors were accepted; only those that are signed and valid can enter the catalog. OAuth authorization then occurs for the individual user and is not part of the import count.

8. Trust boundary and runtime controls

Importing a skill does not attest that its code is benign. The importer checks the wrapper and contract it generates, but it does not completely analyse every received script. Before import, the operator must therefore verify the origin of the whole package, review its scripts, and grant only the required capabilities and credentials.

When bwrap is available, the runtime builds a sandbox from the manifest and admitted capabilities. If it is unavailable, or the sandbox was explicitly disabled, the executor still runs in a separate process and the runtime checks still apply, but the filesystem and network isolation supplied by bwrap is absent.

Executors maintained directly by Metnos follow release review, tests, signing, and policy; imported executors add specific provenance, admission, and audit. Neither origin is “trusted by definition.” In the ordinary flow, L6 also does not approve when its verifier is unavailable: the plan is rejected with an explicit reason.

9. Going deeper

Metnos — importing skills