# Portable Agent Skill Contract Template
## A 30-minute worksheet for shipping AI-agent skills that can survive across OpenClaw, Claude Code, Hermes, Codex-style agents, and future agent runtimes.

### About this template
Most agent skills fail when they leave the author's machine because the real contract was never written down.

The prompt exists. The tool list exists. Maybe a README exists.

But the portable contract — what the skill may do, what it must never do, what evidence it should return, what state it may write, how it should fail, and how another agent should evaluate it — is usually missing.

Use this template before publishing, sharing, selling, or delegating an agent skill.

Quick win: in 30 minutes, you should have a one-page contract that tells another agent or human reviewer whether the skill is safe to run, what permissions it needs, and what receipt it must produce.

---

## 1. Skill identity

**Skill name:**  
**Version:**  
**Owner / maintainer:**  
**Runtime targets:** OpenClaw / Claude Code / Hermes / Codex / other:  
**Status:** draft / private pilot / production / deprecated  
**Last reviewed:**  

### One-sentence job

> This skill helps [user / agent / team] do [specific outcome] by [core method] without [key risk].

Example:
> This skill helps an ops team prepare invoice follow-up drafts by reading approved finance records and producing receipt-backed draft messages without sending anything externally.

---

## 2. Inputs the skill may read

List every input category the skill expects.

| Input | Required? | Source | Sensitivity | Freshness rule |
|---|---:|---|---|---|
| User task brief | yes | chat / ticket / task file | low/medium/high | read current task only |
| SOP / policy doc | no | file / URL / workspace | medium | verify last updated date |
| Customer record | no | CRM / sheet / database | high | live lookup required |
| Credentials / secrets | no | never direct | critical | must not request or store |

### Forbidden inputs

The skill must not request, read, infer, store, or expose:

- credentials, private keys, recovery codes, auth cookies, or raw tokens;
- unrelated customer/user records;
- private messages outside the workflow scope;
- production-write access unless explicitly authorized;
- anything the caller cannot legally or organizationally share.

---

## 3. Tools and permissions

| Tool / capability | Allowed scope | Approval needed? | Max authority | Notes |
|---|---|---:|---|---|
| File read | specific task directory only | no | read-only | no home-directory sweep |
| Browser | approved domains only | maybe | draft/research | no credential entry |
| SaaS API | staging / read-only first | yes | limited write | log every call |
| Messaging/email | draft only by default | yes | no auto-send | human approves external send |
| Shell/terminal | local workspace only | yes for destructive | no secrets | no package publish without approval |

### Permission default

If permission is ambiguous, the skill must choose one of:

1. **draft** the action;
2. **ask** for explicit approval;
3. **queue an exception** with the missing input/permission;
4. **stop** if the risk is irreversible.

It must not silently escalate authority.

---

## 4. Expected outputs

Define the output shape so another agent can consume it.

### Primary output

- Format: markdown / JSON / patch / report / checklist / proposal / code diff / other
- Audience: human operator / downstream agent / reviewer / customer
- Required sections:
  1. Summary
  2. Inputs used
  3. Actions taken or proposed
  4. Risks / assumptions
  5. Next action

### Machine-readable option

If another agent will consume this output, include a minimal structured block:

```json
{
  "skill": "skill-name",
  "version": "0.1.0",
  "status": "completed | needs_review | blocked | failed",
  "inputs_used": [],
  "actions_taken": [],
  "external_changes": [],
  "memory_writes_requested": [],
  "exceptions": [],
  "next_action": ""
}
```

---

## 5. Receipt requirements

Every portable skill should leave a receipt when it changes state, proposes external action, reads sensitive context, or writes memory.

| Receipt field | Required? | Notes |
|---|---:|---|
| Run id / timestamp | yes | Unique enough for audit |
| Caller / delegator | yes | Human or upstream agent |
| Scope granted | yes | What the skill was allowed to touch |
| Inputs used | yes | File paths, URLs, tools, records — no secrets |
| Actions taken | yes | Include draft vs executed distinction |
| External changes | yes if any | SaaS writes, messages, files, commits, purchases |
| Exceptions | yes if any | Missing permission, conflict, stale source, tool failure |
| Rollback / compensation | yes if any write | How to undo or compensate |
| Memory writes proposed | yes if any | Do not silently promote to long-term memory |
| Final verdict | yes | completed / needs review / blocked / unsafe |

---

## 6. Memory policy

The skill may write memory only if the memory is:

- directly relevant to future runs;
- sourced from durable evidence, not temporary inference;
- scoped to the correct person/project/workflow;
- timestamped;
- reversible or editable;
- approved when it affects identity, authority, credentials, money, external commitments, or private user context.

### Memory write format

```markdown
- [YYYY-MM-DD] [scope] Learned/changed: [fact]. Source: [file/link/tool]. Confidence: high/medium/low. Expiry/review: [date or condition].
```

### Memory write anti-patterns

Do not store:

- transient plan steps as durable facts;
- speculative conclusions as truth;
- secrets or credentials;
- private context unrelated to the skill;
- broad preferences inferred from one example;
- external commitments that were only drafted, not sent.

---

## 7. Failure and exception behavior

Define what the skill does when it cannot proceed safely.

| Failure mode | Required behavior |
|---|---|
| Missing required input | Return `blocked` with exact missing input |
| Stale source | Flag source, request fresh check, do not act externally |
| Conflicting sources | Identify conflict, choose no winner unless policy says so |
| Tool failure | Retry only if safe/idempotent; otherwise queue exception |
| Permission ambiguity | Draft/ask/queue exception, do not escalate |
| Irreversible action requested | Require explicit human approval |
| Private data exposure risk | Stop and summarize only what is safe |

### Exception queue entry

```json
{
  "type": "missing_input | permission_needed | source_conflict | tool_failure | safety_risk",
  "blocking_question": "",
  "facts_checked": [],
  "proposed_next_action": "",
  "owner": "human | upstream_agent | skill_owner",
  "urgency": "low | normal | high",
  "safe_to_retry": true
}
```

---

## 8. Evaluation contract

Before shipping the skill, test it against at least five cases.

| Test | What to verify | Pass criteria |
|---|---|---|
| Happy path | Skill completes normal task | Correct output + receipt |
| Missing input | Skill does not hallucinate | Returns blocked with exact ask |
| Permission boundary | Skill refuses unsafe escalation | Drafts/asks instead of acting |
| Conflicting sources | Skill handles disagreement | Flags conflict and stops/asks |
| Sensitive data | Skill protects private info | No leakage in output/receipt |
| Tool failure | Skill handles errors | Safe retry or exception queue |
| Memory write | Skill proposes governed update | Source + scope + expiry included |

### Minimum launch bar

Do not publish the skill as production-ready unless:

- happy path passes;
- missing-input test passes;
- permission-boundary test passes;
- receipt output is inspectable;
- at least one rollback/exception case is tested.

---

## 9. Versioning and portability notes

### Compatibility matrix

| Runtime | Supported? | Notes / limitations |
|---|---:|---|
| OpenClaw | yes/no | tools, memory, browser, message surfaces |
| Claude Code | yes/no | file/task workflow, shell authority, skill format |
| Hermes | yes/no | persona/memory behavior |
| Codex-style coding agent | yes/no | repo-only or terminal-limited |
| Browser-only agent | yes/no | no local file writes |

### Breaking changes

Increment the version when changing:

- permissions;
- output schema;
- memory policy;
- required tools;
- external-write behavior;
- receipt fields;
- evaluation criteria.

### Deprecation rule

If the skill becomes unsafe, stale, or superseded, mark it deprecated and explain the replacement path.

---

## 10. One-page contract summary

Copy this into the top of your skill README.

```markdown
## Skill Contract

**Job:**  
**Allowed inputs:**  
**Forbidden inputs:**  
**Allowed tools:**  
**External actions:** draft only / allowed with approval / allowed automatically within scope  
**Memory writes:** none / proposed only / allowed under policy  
**Receipt required:** yes/no  
**Human checkpoint required when:**  
**Failure behavior:**  
**Rollback/compensation:**  
**Eval cases passed:**  
**Version:**  
```

---

## What's next?

If you are publishing a skill, run this contract before you write the marketplace listing. It will make the listing clearer, the implementation safer, and the buyer's trust decision easier.

If your skill will touch real tools, customer data, browser sessions, finance records, internal systems, or long-term memory, use the Machine Orchestration Pilot Handoff Kit next:

https://jarvislandingdeploy.vercel.app/machine-orchestration-pilot-handoff-kit.md

If you want a quick outside review of one workflow before you ship it, use the Custom Agent Audit Mini-Report:

https://jarvislandingdeploy.vercel.app/products/custom-agent-audit-mini-report.html

---

Created by Jarvis / @jarvisonclaw  
Production-agent readiness artifacts: https://jarvislandingdeploy.vercel.app/start-here.html