agentleFS
renanlidorenanlido/tia-harness/skills/tia-handoff/SKILL.md

tia-handoff

Skill12 starsChanged 30 days agoMITView on GitHub

Prepare a human-approval envelope for a GATED operation — download / CPU-STOP (G3), go-online (G4), network scan (G7), credentials (G6: master secret, UMAC, upload / block / certificate passwords, password policy), safety/F (G5). Use when the user wants to "download / deploy / go online / commission", or after tia-verify is clean and the next step touches the physical controller. Class GATE: this skill NEVER performs the gated action — it produces the plan + planHash + exactly what the human must approve, and the precise resume call. The AI never approves, never invents a secret, never deploys F autonomously. Not for building (tia-scaffold) or compiling (tia-verify).

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If no tia_* tool is available, the tia MCP is not connected: say so and stop.

    line 24
  2. Very specific:

    Never report success after an error, never retry a refused call with changed arguments, and never cross a human gate: relay a …

    line 26
  3. Very specific:

    After tia-verify is clean and the user wants to download / deploy / go online / scan / commission.

    line 31
  4. Very specific:

    STOP: Do not call tia_download with approved:true yourself.

    line 88
  5. Distinctive:

    Only the human answers it: Never answer, dismiss or work around the dialog yourself.

    line 115

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

tia-handoff — prepare the gate, let a human act (class GATE)

The harness is an assistant up to the gate, never an autonomous commissioner. Anything that touches the physical controller, the network, secrets, or safety stops here: this skill assembles the approval envelope (requires_human_action) — what can be done, what the human must do, the plan + hash, and the exact resume call — and then stops.

Errors and reporting

  • First call tia_ping: continue only if it reports reachable:true and activated:true. activated:null with a busy detail means serve is occupied, not necessarily by an MCP job: poll tia_job_status only for a running job whose jobId is known. Without one, wait/recheck with tia_status; for connect_incomplete, follow the host-inspection handoff in tia_guide {"topic":"gui-gates"}, never retry connect. Otherwise stop, quote its detail and hint verbatim and say that nothing was changed (prerequisites: tia_guide {"topic":"gotchas"}).
  • If no tia_* tool is available, the tia MCP is not connected: say so and stop. Never continue from memory and never work around it with hand-made HTTP calls (they bypass the MCP's gate checks).
  • On a tool error (isError:true), quote its error and kind verbatim, relay its hint, and state what was done and what was not. Apply only the remedy the hint or this skill names, at most once; otherwise stop and ask.
  • Never report success after an error, never retry a refused call with changed arguments, and never cross a human gate: relay a requires_human_action answer verbatim and wait for the human.
  • status:"running" + jobId identifies a running job: poll tia_job_status {jobId} without repeating the original call. On kind:"busy", poll only for a running job whose jobId is known (e.g. details.jobId); without one, wait/recheck with tia_status. For connect_incomplete, follow the host-inspection handoff in tia_guide {"topic":"gui-gates"}, never retry connect. After a timeout, check the state before repeating anything.

When to use

  • After tia-verify is clean and the user wants to download / deploy / go online / scan / commission.
  • Whenever a step needs a secret (master secret, UMAC, an upload / block / certificate password), a password-policy decision, or touches F (safety).

The gates (and the tool that fronts each)

GateActionToolWhat the human must approve
G1open/connect project (1st time)tia_connect (+ tia_show_ui)confirm the TIA trust dialog on the serve host
G3download (CPU STOP → possible program delete → overwrite → restart)tia_downloadthe verified plan + software fingerprint + EVERY loadPreview.willConfirm entry: StopAll, ResetModule = DeleteAll (a different program on the CPU is deleted), OverwriteSystemData, ConsistentDownload of blocks and alarm text libraries, StartModule, and UpgradeTargetDevice (only if opted in; without it a CPU that needs it refuses the load)
G4go online (connect to live CPU)tia_onlineit is safe to connect to the target machine
G4station upload (read CPU into project)tia_uploadit is safe to connect to the target machine AND the open project is a dedicated backup project (the upload adds a new station — skill tia-backup)
G7network scan (accessible devices)tia_accessible_devicesprobing the local network via the PG/PC NIC
G6credentials: master secret / UMAC / upload read password / block know-how password / certificate password / password policy / local-session logon dialogtia_mastersecret_set ({plc, password}), tia_mastersecret_reset, tia_connect (umacUser/umacPassword), tia_upload (password), tia_block_protect, tia_certificate_import, tia_password_policy_set, tia_local_session_open (a UMAC-protected session may wait on a Siemens logon dialog on the serve host)supply the secret / decide the policy / answer the logon dialog (human/credential vault); a reset only on the human's explicit request
G5safety/F author·modify·download—never autonomous; F deploy is a human, gated action

Two classes of human interaction. The table above is approval gates — a human approves an action that touches the controller, network, secrets, or safety. There is a second class: GUI-config handoffs — fresh 1214C PUT/GET, OPC UA license selection and HR mapping need an owner-prepared source; tia_device_from_mastercopy can inherit them into a NEW station, not grant entitlement or set an arbitrary existing CPU. G1 trust confirmation remains human-only. During scaffold/verify, do not blindly retry a missing license/interface; give the exact steps in tia_guide {"topic":"gui-gates"} (the harness guide's "Human interaction points (GUI gates)").

Procedure (in order)

  1. Precondition (Gd9). Confirm the latest tia_compile is clean (errors:0) via tia-verify. Never prepare a download for an inconsistent project.
  2. Discover the path (no gate, no scan). Connection mode / PG-PC interface / target interface are localized names — discover them with tia_pg_interfaces (reads what TIA already knows about the CPU's DownloadProvider, plus each adapter's OS status; performs no network scan). Only reach for tia_accessible_devices (GATE G7, a real scan) when tia_pg_interfaces doesn't resolve the interface you need.
  3. Dry-run the download. tia_download { dryRun:true } asks serve for a verified plan: a fresh compile, the connection resolved, and the software fingerprint (content hash of blocks/UDTs/tag tables — NOT hardware, system block groups or technology objects; falls back to modification dates when a block has no fingerprint provider). Only a ready plan returns a planHash — a single-use token that expires (TIA_PLAN_TTL_MS, default 15 min) and lives only in this MCP process — and a loadPreview.willConfirm list: every selection serve will make during the load. Nothing is sent to the CPU.
  4. Emit the handoff envelope (requires_human_action):
    • canDo — e.g. "download to PLC_1".
    • youMustDo — the concrete physical consequence + confirm it is safe on the target line.
    • loadPreview — reproduce every loadPreview.willConfirm entry of the dry-run answer, none dropped or squeezed into "STOP → overwrite → restart": the CPU STOPS (StopAll); ResetModule = DeleteAll deletes a DIFFERENT program already on the CPU; system data is overwritten; blocks and alarm text libraries download consistently; the CPU restarts (StartModule); UpgradeTargetDevice is confirmed only with allowUpgradeTargetDevice:true, otherwise a CPU that needs it refuses the load and may already have been stopped; any other dialog serve does not recognise is left untouched and can abort the load.
    • plan + planHash + fingerprint — show the human both: the hash binds the approval to this exact plan AND this exact software content — NOT the hardware configuration. Re-plan (new dryRun) + fresh human approval only if the hardware configuration changed AFTER the dryRun that produced the token — the fingerprint cannot detect that change, so confirm with the human that nothing hardware-side moved; never reuse the old token for changed hardware.
    • resume — the precise call a human runs after approving: tia_download { approved:true, planHash:"<the hash>", ... } (the SAME parameters as the dry-run).
  5. STOP. Do not call tia_download with approved:true yourself. A human approves out-of-band and runs the resume call (or explicitly instructs you to, with the hash).
  6. On approved:true, serve re-checks the fingerprint inside the download call (no window between check and load) and answers 409 plan_stale if the software changed since the plan — start over with a new dry-run and a new approval. allowUpgradeTargetDevice: true (TIA's "upgrade the target device" confirmation, #31) is part of the approved plan; never add it without the human's yes — without it, a CPU that requires it refuses the load with 409 upgrade_target_device_required (check the CPU state before retrying: earlier confirmations in the same pass, like StopAll, cannot be undone).
  7. The other gates. G4 go-online and G7 scan: call tia_online / tia_accessible_devices once WITHOUT confirm — it returns the requires_human_action handoff and touches nothing; relay it verbatim and STOP. Only after the human's explicit yes, repeat the same call with confirm:true (there is no token: the human's yes is the approval). For tia_online that call must repeat the SAME connectionMode, pcInterfaceName, pcInterfaceNumber and targetInterfaceName as the handoff's plan: without connectionMode or pcInterfaceName it is refused (connection_fields_required) and nothing is sent. G6: tia_mastersecret_set and the umac* fields of tia_connect take only a secret the human typed; so do the passwords of tia_block_protect and tia_certificate_import, and tia_password_policy_set takes only values the human decided. A station upload (G4) is the tia-backup skill.

The confirmation dialog (when the client supports it)

A client that supports elicitation shows its own confirmation dialog before a gated call goes through: tia_download with approved:true, and tia_upload, tia_online and tia_accessible_devices with confirm:true. A client without it behaves as before.

  • Only the human answers it. Never answer, dismiss or work around the dialog yourself.
  • It never replaces the flow above. dryRun → human approval → the flag with the planHash still applies in full: the dialog only checks the human's answer, and serve's approval token stays the authority. Passwords (G6) are never asked there.
  • A refusal stops the call. declined_by_human / cancelled_by_human (a result, not an error) means the human refused: nothing was sent and the plan stays valid until its TTL (the token was not consumed). STOP; do not retry unless the human asks you to.
  • elicitation_failed (isError:true) means the dialog could not be shown or answered: nothing was sent. Relay it and STOP.

The token's failure modes (reasonCode on a download_approval handoff)

A successful dry-run is NOT a handoff — it returns status:"plan_ok" with the planHash. reasonCode:"not_approved" appears only when calling the real download without approved:true.

reasonCodeMeaningWhat to do
not_approvedCalled without approved:true (no token presented)Re-run the dry-run, get human approval, call with approved:true + the planHash
unknownThis planHash was not issued by this MCP process (or it restarted)Get a fresh dry-run
expiredThe token's TTL passedGet a fresh dry-run
consumedThis token was already used (single-use)Check the CPU / tia_job_status before anything else
plan_mismatchThe parameters differ from the approved planRe-review with the ACTUAL parameters
outcome_unknownThe download call itself failed AFTER the token was consumed (network/timeout/serve error)The token is SPENT and cannot be reused — check the CPU state directly and tia_status/tia_job_status BEFORE requesting a new plan; do NOT retry the same call

serve_too_old is NOT a reasonCode: a serve without POST /plcs/{plc}/download/plan (< app v1.6.0) fails the dry-run with an ordinary isError:true result with kind:"serve_too_old" — update the app, never fall back to the unverified path.

Hard guarantees

  • Never auto-approve / auto-deploy. This skill outputs a plan + the resume instructions; it does not perform the gated action. approved:true + a matching planHash only ever come from an explicit human decision.
  • Secrets are human-supplied (G6). Master secret, UMAC and the upload / block / certificate passwords come from a human or a credential vault — never invented by the AI, never logged, never put in .mcp.json. Password-policy values (tia_password_policy_set) are the site's security decision: the human decides them, the AI never picks them.
  • Safety never autonomous (G5). F-program author/modify/download is always a gated, human action. The harness only reports F (signatures); the safety-reviewer is read-only.
  • Plan binding. The download executes only with the exact planHash from the dry-run — a changed plan invalidates the approval (re-review). serve re-verifies the fingerprint again inside the real download — the token is never trusted blindly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.