1. What a skill is, in thirty seconds

A skill is a package that describes how to use a service or a family of functions. Its entry point is SKILL.md; the package may also contain scripts and references needed at runtime. Metnos does not execute it directly: it translates the package 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 and can be invoked in natural language, while the manifest continues to record their 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 signs the result. This reduces the granted authority and makes it observable, but it does not certify third-party code as benign: provenance and source still require judgment.

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 SKILL.md.
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 affinity terms; a deterministic fallback is used when it is unavailable.
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 audit 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. Remote sources are kept in the local cache for a default maximum of seven days; an operator can force a fresh fetch.

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.

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

Ask Metnos with a request like this example: “What appointments are on my work calendar tomorrow?” If the Google Workspace capability is admitted, enabled, and connected to the user's account, the catalog exposes the event-specific executor. Other examples are “Find unread messages from Anna,” “Read the contents of this Drive file,” and “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 perform complete static analysis of every received script. Before import, the operator must verify origin and fingerprint, review the scripts, and grant only the required capabilities and credentials.

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