Documentation Review: Sampling, Skills, Manifest, and Host API Grant Issues

Developers
1

Hi Anna team,

I recently reviewed the Sampling, Skills, App Manifest, UI Manifest, and Host API Grants sections of the documentation.

During the review, I cross-checked the docs against the current production implementation, Anna CLI, SDK examples, CLI templates, and local runtime behavior.

Overall, the documentation is already quite comprehensive, but I found several areas where the docs appear to be out of sync with the current implementation, contain outdated examples, or omit behavior that developers are likely to encounter in practice.

Sampling

1. Naming: “Per-invoke caps (v1 limits)”

“Per-invoke caps (v1 limits)” can easily be confused with protocol v1/v2.

It would be clearer to use the terminology already present in the source code: phase1.

2. max_tokens should be required

The documentation currently describes max_tokens as having a default value of 8192.

However, in the production implementation, maxTokens is required. Omitting it results in error -32004.

Reference:

~/Anna/_internal/src/executa/sampling.c:6766

3. Missing parameters in create_message()

The documented signature appears incomplete.

Current documentation:

create_message(..., metadata: Optional[dict] = None, timeout: float = 90.0)

Actual SDK signature:

metadata: Optional[dict] = None,
response_format: Optional[dict] = None,
on_unsupported: Optional[str] = None,
timeout: float = 90.0

Reference:

anna-executa-examples/sdk/python/executa_sdk/sampling.py:136-151

4. Missing error code: SAMPLING_ERR_UNSUPPORTED_RESPONSE_FORMAT

The documentation omits error code -32010 (SAMPLING_ERR_UNSUPPORTED_RESPONSE_FORMAT).

This error code exists in both the SDK and CLI.

References:

anna-executa-examples/sdk/python/executa_sdk/sampling.py:64
~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/sampling-DwV7VPfT.js:44-48

5. -32008 is also returned outside invoke context

The documentation currently associates -32008 only with invoke cancellation.

However, the implementation also returns -32008 when:

  • invoke_id is missing

  • sampling is attempted outside an invoke context

Reference:

~/Anna/_internal/src/executa/sampling.c:12658-12683

Skills

6. metadata.dependencies

The documented example does not match the current implementation.

For example, focus-coach/SKILL.md uses:

metadata:
  matrix:
    requires:
      tools:

rather than:

metadata.dependencies

7. metadata.execution_mode

The current CLI reads execution_mode from the top level of executa.json, not from metadata.execution_mode in SKILL.md frontmatter.

Reference:

dist/manifest-Bljz8Y6T.js:117

8. Supporting files are not currently packaged with Skills

The documentation suggests that supporting files can accompany a Skill.

However, the current CLI only loads the contents of SKILL.md.

In a minimal test:

executa.json
  executa_type: "skill"

SKILL.md

templates/example.json

After calling loadExecutaManifest(), the parsed result contains:

kind
path
raw
slug
name
version
executa_type
description
changelog
skillContent
executionMode
distribution

skillContent only contains the contents of SKILL.md.

No supporting files are included, and there are no fields such as:

supportingFiles
assets
templates

Anna App Manifest

9. ui.bundle is required

The documentation should explicitly state that ui.bundle is a required field.

UI Manifest

10. Only static-spa is currently supported

The CLI validator currently only accepts:

ui.bundle.format = "static-spa"

Any other value results in:

ui.bundle.format currently only supports 'static-spa'

Reference:

dist/cli.js:199

11. bundle.external_origins

The documentation should mention that:

  • Origins must start with https://

  • Wildcards (*) are not allowed

Reference:

dist/cli.js:204

UI Host API Grants

12. Tool access is not controlled solely by host_api.tools

The documentation currently implies that host_api.tools is the sole source of tool authorization.

However, if host_api.tools is omitted or empty, the CLI ACL still allows tools.invoke and tools.list for tools declared in:

  • required_executas

  • optional_executas

The docs should clarify how this behavior interacts with the dispatcher rejecting ungranted calls.

Reference:

dist/cli.js:142-147

13. Missing Host API grants

The documentation currently omits:

host_api.image
host_api.upload

These Host API grant types should also be documented.

Summary

Most of these appear to be synchronization issues between the documentation and the current CLI, SDK, examples, and production implementation.

The highest-priority areas to align are:

  • Sampling API signatures, required parameters, and error codes

  • Skill manifest/frontmatter conventions

  • Current UI manifest validation rules

  • Host API grant and ACL behavior

I’m happy to provide minimal repro cases, CLI output, or additional source references if useful.