Skill Packages and skill.md

Draft 0.1 — 2 August 2026
An ANUKA skill is a versioned instruction and integration package. It is not executable authority, a secret store, a guarantee of model behavior, or a substitute for server-side policy.

Objective

Skills make repeatable agent workflows legible to humans, tools, repositories, and compatible agent hosts.

A skill should answer:

what outcome it supports;
when it should and should not be used;
what tools and data it needs;
what approvals are required;
how outputs are verified;
who maintains it;
how it changes over time.

The rule is:

A skill may teach an agent how to work; only an authorization grant may permit the work.

Package layout

Recommended package:

skills/<skill-name>/
├── skill.md
├── skill.json
├── schemas/
│   ├── input.schema.json
│   └── output.schema.json
├── prompts/
├── examples/
├── tests/
├── policies/
├── CHANGELOG.md
├── LICENSE
└── README.md

skill.md is the primary human- and model-readable workflow document.

skill.json is the machine-readable manifest.

Skill identity

Every skill has:

stable ID;
package name;
display name;
semantic version;
owner;
repository and source commit;
license;
status;
protocol compatibility;
tool dependencies;
input and output schemas;
risk tier;
data classification ceiling;
required capabilities;
approval requirements;
artifact digest.

A copied or forked skill must use a distinct identity unless it remains an authorized release of the same package.

skill.md frontmatter

Example:

---
id: network.anuka.skills.review-contribution
name: Review Contribution
version: 0.1.0
status: draft
owner: ANUKA Foundation
license: Apache-2.0
risk_tier: A2
capabilities:
  - contribution.read
  - evidence.package.analyze
tools:
  - anuka.contribution.get@1
  - anuka.evidence.validate@1
input_schema: ./schemas/input.schema.json
output_schema: ./schemas/output.schema.json
last_verified: 2026-08-02
---

The frontmatter is metadata, not proof that the declared controls are enforced.

Required skill.md sections

Purpose

What concrete outcome the skill supports.

Use when

Conditions under which the skill is appropriate.

Do not use when

Known exclusions, high-risk contexts, unsupported decisions, or missing evidence.

Inputs

Required and optional inputs, data classification, and consent requirements.

Tools and resources

Exact tool contracts, resources, versions, and expected trust status.

Workflow

Ordered reasoning and execution stages.

Approval checkpoints

Actions requiring human or organizational authorization.

Output contract

Expected structured and human-readable results.

Verification

Checks that distinguish a plausible output from an accepted result.

Failure handling

What to do when data is missing, tools fail, authorization expires, or results conflict.

Safety and privacy

Data minimization, prohibited disclosures, retention, and high-impact boundaries.

Examples

Representative valid and invalid cases.

Workflow language

A skill should use clear imperative stages.

Example:

resolve the current principal and product scope;
verify that the contribution is assigned and reviewable;
retrieve only the consented evidence fields;
validate evidence package integrity and status;
compare work against frozen acceptance criteria;
identify uncertainty and missing evidence;
produce a review proposal;
request human approval before acceptance or rejection.

Skills should not rely on hidden chain-of-thought or require a model to reveal private internal reasoning.

They should require auditable summaries, evidence references, and decision factors.

Machine-readable manifest

skill.json enables discovery and validation.

Example:

{
  "$schema": "https://schemas.anuka.network/skill-package/1.0.0/schema.json",
  "id": "network.anuka.skills.review-contribution",
  "version": "0.1.0",
  "entrypoint": "skill.md",
  "tools": [
    {
      "contract": "anuka.contribution.get",
      "major": 1,
      "required": true
    }
  ],
  "risk_tier": "A2"
}

The manifest may be generated from frontmatter but the released artifact must have one canonical normalized representation.

Skill types

Informational

Reads public or authorized resources and produces analysis.

Drafting

Creates proposals, documents, code changes, or communications without publishing them.

Review

Evaluates artifacts against criteria and produces findings.

Operational

Invokes reversible tools under a bounded grant.

Orchestration

Coordinates multiple tools or tasks.

High-impact assisted

Prepares actions requiring an exact human approval.

A high-impact skill cannot mark itself autonomous through metadata.

Tool dependencies

Dependencies specify:

tool contract ID;
compatible major version;
required or optional;
expected risk annotation;
fallback behavior;
minimum server trust status.

A skill must fail safely when an incompatible or unverified tool is supplied.

Matching only by a human-readable tool name is insufficient.

Resource dependencies

A skill may declare resource types such as:

Foundation specification;
product manifest;
Passport presentation;
contribution evidence package;
governance decision;
repository file;
task artifact.

Resource access remains subject to authorization and consent.

Capability requirements

The package declares the maximum capability set it may request.

At runtime, the task receives a subset.

A skill must adapt or stop when a required capability is absent. It must not prompt the model to discover an unauthorized workaround.

Approval policy

The skill declares checkpoints such as:

approvals:
  - before: contribution.accept
    mode: exact_action
  - before: external.message.send
    mode: exact_content

Runtime policy can require stricter approval than the skill declares.

The skill cannot weaken organization or constitutional controls.

Prompt assets

Prompt files may provide templates, but must:

separate trusted instructions from untrusted data;
avoid embedding secrets;
identify variables;
define output format;
include injection resistance guidance;
remain versioned;
have tests.

Prompts are implementation assets, not universal truth about model behavior.

Examples and fixtures

Each skill should contain:

successful example;
missing-data example;
authorization-denied example;
malicious-input example;
tool-failure example;
ambiguous-result example;
approval-required example;
expected structured output.

Examples must use synthetic or properly licensed data.

Skill tests

Static tests

manifest validation;
link and dependency resolution;
schema validation;
prohibited secret detection;
required section presence;
version consistency;
license presence.

Contract tests

tool input and output compatibility;
capability-denial behavior;
approval checkpoints;
safe retry behavior;
error mapping.

Scenario tests

valid workflow;
prompt injection;
conflicting evidence;
expired consent;
partial tool failure;
high-impact action request;
privacy redaction.

Evaluation tests

Model-dependent evaluation may measure task quality, but cannot replace deterministic policy and schema tests.

Verification criteria

A skill output is accepted only through its declared verification method.

Verification may include:

JSON Schema validation;
unit or integration tests;
external source confirmation;
calculation recomputation;
reviewer approval;
conformance test;
deployment smoke test;
ledger reconciliation.

“Looks correct” is not a verification policy.

Installation

Skill installation records:

package ID and version;
source registry;
artifact digest;
signer or provenance;
installer principal;
organization and product scope;
enabled tools;
granted capabilities;
review date;
status.

Installing a skill must not automatically grant all declared capabilities.

Registry

The registry exposes:

canonical package metadata;
versions;
owner and operator;
source repository;
artifact digest;
license;
verification status;
conformance results;
known vulnerabilities;
deprecation;
supported hosts and protocols.

Community packages and verified Foundation packages must be visibly distinct.

Trust levels

Unreviewed

Package is discoverable but not reviewed.

Schema validated

Manifest and package structure pass automated validation.

Maintainer verified

Ownership, source, and release provenance are verified.

Conformance tested

Declared scenarios and tool contracts pass current tests.

Security reviewed

Package received a scoped security review for a declared version.

Trust is version-specific and can expire or be revoked.

Signing and provenance

Released packages should include:

immutable source reference;
artifact digest;
build provenance where generated;
maintainer identity;
signature or attestation;
dependency lock or bill of materials where applicable.

A signature establishes who signed the artifact and integrity since signing. It does not guarantee the workflow is safe or correct.

Versioning

Skills use Semantic Versioning for their public workflow contract.

Major changes include:

materially different purpose;
broader capability requirements;
new external side effects;
changed approval semantics;
incompatible input or output;
changed privacy behavior.

Minor changes include compatible new options or supported tools.

Patch changes fix wording, examples, tests, or compatible defects.

Risk increases may require a major version even when schemas remain compatible.

Deprecation

A deprecated skill identifies:

replacement;
reason;
migration guide;
warning date;
end-of-support date;
removal date where applicable;
security urgency.

Installed packages remain visible after deprecation so historical task records can be interpreted.

Forks

Openly licensed skills may be forked under their license.

A fork must not claim:

Foundation verification;
original maintainer approval;
access to private registries;
trademark rights;
compatibility it has not tested.

Secrets

Skills must never contain:

API keys;
access tokens;
private keys;
production credentials;
personal data fixtures;
passwords;
hidden remote-code loaders.

Secrets are resolved at runtime through approved scoped credential mechanisms.

Remote content

A skill may reference documentation or data resources, but executable instructions used for a released version should be pinned or integrity-verified.

The package must not silently fetch and execute mutable remote code.

Remote model prompts and configuration are treated as versioned dependencies when they materially affect behavior.

Licensing

Each package declares licenses for:

documentation and instructions;
executable code;
schemas;
examples and assets;
third-party dependencies.

Software should use an OSI-approved license when described as open source.

Documentation rendering

The Foundation site should render skills as readable documentation while preserving the repository files as the canonical source.

The rendered page should show:

status and version;
risk tier;
required tools and capabilities;
approvals;
verification;
maintainer;
last review;
source link;
install command or registry reference.

MVP skill set

Initial skills may include:

search Foundation documentation;
validate an ANUKA schema;
inspect a Presence manifest;
evaluate an opportunity fit;
draft a contribution proposal;
summarize consented evidence;
review a contribution against criteria;
compare governance proposals;
generate a conformance report;
prepare an incident timeline.

High-impact finance, employment, sanctions, constitutional, and production-release skills remain assisted-only.

Acceptance criteria

every skill has stable identity and version;
skill.md contains purpose, exclusions, workflow, approvals, verification, and failure handling;
machine manifest validates;
tool dependencies use versioned contract IDs;
package capabilities are maxima, not automatic grants;
tests include injection, denial, and partial failure;
installation records artifact digest and scope;
registry trust level is visible and version-specific;
secrets and mutable remote code are prohibited;
risk increases trigger appropriate versioning and review;
forks cannot impersonate verification;
skill output is not accepted without declared verification.

Sources

Verification record

Sources opened and checked: 2 August 2026
Package schema: To be created
Registry implementation: Not selected
High-impact autonomous skills: Prohibited in MVP