Koder Skill Format (SKILL.md)

Abstract

A Koder Skill is a self-contained, user-curated reusable instruction set that a Koder AI agent loads on demand to perform a recurring task. Skills are authored, versioned, and distributed as directories containing one SKILL.md file (mandatory) plus optional attached scripts and fixtures. This specification defines the on-disk layout, the YAML frontmatter schema, the body conventions, the discovery rules, and the versioning policy.

Companion to:

• TOOLS-013 (/skill-creator slash command — the authoring tool that produces SKILL.md from a successful conversation)
• TOOLS-014 (auto-skill mining — produces draft SKILL.md from clusters of similar past runs)
• AIHUB-023 (registry + signed publishing — how SKILL.md travels to the marketplace)
• AIHUB-024 (Biblioteca UX — how users browse, install, rate)

1. Design philosophy

• Plain-text first. A skill is editable by humans without tooling — open in any editor. No binary blobs in the canonical file.
• Markdown + YAML, nothing else. Frontmatter is YAML; body is CommonMark. Per policies/document-format.kmd, the canonical extension is .md only for SKILL.md (treated as third-party convention compatible with Anthropic Skills and Manus Agent Skills); internal Koder documentation about skills stays .kmd.
• Self-describing. A skill that lists its triggers, inputs, and required tools never needs an external README to be installable.
• Reproducible. Two installations of the same skill version on two machines produce the same agent behaviour (modulo non-deterministic tool outputs).
• Cross-runtime. The same SKILL.md runs under Koder AI, and is syntactically compatible with Anthropic Skills and Manus Agent Skills — Koder-specific fields are namespaced under koder: so foreign runtimes ignore them safely.

2. On-disk layout

A skill is a directory with a fixed name pattern:

~/.koder-ai/skills/<slug>/
├── SKILL.md              ← mandatory; the single source of truth
├── scripts/              ← optional; helpers callable from SKILL.md
│   ├── extract.py
│   └── render.sh
├── fixtures/             ← optional; sample inputs/outputs for tests
│   ├── input.json
│   └── expected.html
└── assets/               ← optional; static files referenced from body
    └── template.html

• <slug> matches ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$ (DNS-label safe, lowercase).
• SKILL.md is the only file required for a valid skill. All others are conventional and optional.
• The slug must match the name in frontmatter (R3.1 below).

2.1 Storage locations

• User-local: ~/.koder-ai/skills/<slug>/ (per-user, not synced by default).
• Workspace: <workspace_root>/.koder-ai/skills/<slug>/ (committed to the user's repo; survives clone).
• Installed from marketplace: same as user-local; AIHUB-024 install flow copies into ~/.koder-ai/skills/<slug>/.
• Bundled (read-only): /opt/koder/skills/<slug>/ (system-wide defaults shipped with Koder Kodix ISO).

Discovery precedence at agent boot: workspace > user-local > bundled. Conflicts are resolved by precedence; the agent logs the shadowed source.

3. Frontmatter schema (R1–R10)

The frontmatter is delimited by --- on its own line at the start and end, contains a YAML mapping, and must include the following keys:

R1 — name (string, required)

The slug. Must equal the directory name. Validated against ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$. Globally unique within a user's installed skill set; collisions resolved by visibility/source per §2.1.

R2 — description (string, required)

One-line human summary, max 200 chars. Used in:

• Biblioteca UI cards (AIHUB-024)
• Agent system-prompt when the skill is auto-loaded
• Search results

R3 — version (string, required)

Semver MAJOR.MINOR.PATCH. Per AIHUB-023 update flow:

• PATCH: bug fix or wording adjustment, no behaviour change
• MINOR: new optional input or tool used; backwards compatible
• MAJOR: breaking change (removed input, semantics change)

R4 — author (string or mapping, required)

Either a string koder_user_id (e.g. rpm32510) or a mapping:

author:
  koder_user_id: rpm32510
  display: Rodrigo Mendonça
  org: Crescer

Used for trust badges in AIHUB-024 marketplace.

R5 — triggers (sequence of strings, required)

Patterns the agent matches against user prompts to auto-load the skill. Each entry is:

• A literal phrase (case-insensitive substring): "comparar produtos",
• A regex with re: prefix: re:^/extract\s+(\w+),
• An intent tag from the standard taxonomy: intent:extract, intent:publish, intent:research (see §6 below).

The agent merges triggers across all installed skills; first match wins (precedence by source per §2.1).

R6 — inputs (sequence of mappings, optional)

Typed slots the skill expects. Each entry:

inputs:
  - name: target_url
    type: url        # url | string | int | float | bool | json | file
    required: true
    description: "Page to scrape"
  - name: max_items
    type: int
    required: false
    default: 10

If required: true and missing, the agent asks the user before running the skill. Validation per policies/regression-tests.kmd — each skill ships test fixtures for the contract.

R7 — outputs (sequence of mappings, optional)

Typed artefacts the skill produces. Same shape as inputs. Used by chained skills (one skill's output feeds the next) and by AIHUB-024 to display "what you get" in the install dialog.

R8 — tools_required (sequence of strings, optional)

The set of TOOLS-registered tools the skill calls. The agent refuses to load a skill if any required tool is unavailable (e.g. browser needs SANDBOX-010; github needs TOOLS-015 + OAuth link). Used by the install flow to prompt the user to grant integrations.

Canonical tool names (registered in services/ai/tools):

• browser (SANDBOX-010)
• web.fetch (AICORE-113)
• web.extract (AICORE-114)
• code.search (EMBED-013)
• github / flow (TOOLS-015)
• slack / jira / webhook (TOOLS-015)
• kdb.query (services/ai/runtime)
• shell (SANDBOX-007)

R9 — model_hints (mapping, optional)

Author preferences for model selection. The agent treats as hints, not commands.

model_hints:
  prefer: opus       # opus | sonnet | haiku
  min_context: 200k
  needs_vision: false
  needs_thinking: true

R10 — koder: namespace (mapping, optional)

Koder-specific fields that foreign runtimes (Anthropic Skills, Manus) ignore safely:

koder:
  workspaces: ["data-extraction", "research"]  # restrict to workspaces
  visibility: unlisted                          # private | unlisted | public
  signing_key: "ed25519:abc..."                 # AIHUB-023 signature
  retention_days: 365                           # auto-archive idle skills

4. Body conventions (R11–R14)

The body after frontmatter is CommonMark. Conventions:

R11 — Sections

Use these top-level headings in this order (each optional except ## Instructions):

## Instructions     ← required; the prose the agent reads
## Steps            ← optional; numbered checklist for predictable flows
## Examples         ← optional; user-prompt → expected-behaviour pairs
## Caveats          ← optional; what NOT to do, edge cases
## References       ← optional; links to docs, related skills

R12 — Calling attached scripts

To invoke a script in scripts/, the body uses fenced code blocks labelled with a directive:

```call:scripts/extract.py
{
  "url": "{{ inputs.target_url }}",
  "max_items": {{ inputs.max_items }}
}
```

The agent serialises the JSON arg, runs the script in the sandbox (SANDBOX-007), and captures stdout as a string the skill body can reference via {{ result }}.

R13 — Templating

Inputs, outputs, and intermediate results are interpolated with Mustache-style {{ }} placeholders. Reserved names:

• {{ inputs.<name> }} — input slot value
• {{ outputs.<name> }} — output slot value (write-once)
• {{ result }} — last script invocation's stdout
• {{ now }} — RFC3339 timestamp
• {{ workspace }} — current workspace name
• {{ user.koder_user_id }} — invoking tenant

R14 — Length budget

Hard cap 8000 characters total (frontmatter + body). Skills longer than that should split into multiple skills with explicit chaining (outputs of A → inputs of B). Rationale: skill prompt cost amortises across reuse; long skills become expensive.

5. Versioning policy (R15–R17)

R15 — Immutable releases

Once version: X.Y.Z is published to AIHUB-023, the byte content is immutable. Fixes require a new version bump.

R16 — Deprecation lifecycle

Skill marked deprecated in latest version → still installable for 90 days, then hidden from search but installed copies keep working. After 180 days the skill is archived (AIHUB-024 Library still shows it under "Archived").

R17 — Update prompts

When a user has v1.2.x installed and v1.3.0 is available, the agent's next session prompts (AIHUB-024): "Skill X has v1.3.0 available (you have v1.2.4). Update? [diff] [yes] [skip]". Diff is generated client-side from cached metadata.

6. Intent taxonomy (for triggers: intent:*)

Closed vocabulary of high-level intents the agent classifies user prompts into. Skills declaring intent:<x> auto-load when the agent classifies the prompt as <x>.

Intent classifier lives in services/ai/ai core; updates to this taxonomy require a spec revision (PATCH bump of this spec).

7. Test contract (T1–T8)

Every skill SHOULD ship test fixtures in fixtures/ and a skill-test.toml config. T1–T8 baseline tests are defined per policies/regression-tests.kmd:

• T1 — Frontmatter parses without warnings
• T2 — name matches directory + slug regex
• T3 — Semver well-formed
• T4 — Triggers compile (regex valid, intent in taxonomy)
• T5 — tools_required all registered in TOOLS
• T6 — Body length ≤ 8000 chars
• T7 — Each ## Examples example runs through skill and produces output matching fixtures/expected.*
• T8 — Negative: malformed input → skill refuses with KAI-SKILL-… error per specs/errors/user-facing-messages.kmd

The CLI koder-skill validate <dir> runs T1–T6 statically; T7/T8 require sandbox.

8. Compatibility with foreign runtimes

Koder Skill SKILL.md files are designed to be loadable by:

• Anthropic Skills (claude.ai Skills): all R1–R9 fields map 1:1; koder: namespace ignored. Body conventions identical.
• Manus Agent Skills: same. Manus parses Markdown body verbatim; tools_required mapped to Manus tool registry.

Conversely, importing an Anthropic Skill into Koder AI requires only adding koder: fields if marketplace publishing is desired (AIHUB-024 install flow auto-fills with safe defaults).

9. Error model

Skill-related errors follow specs/errors/user-facing-messages.kmd with prefix KAI-SKILL-:

Each code maps to a human pt-BR/en-US message + "Ver detalhes" expand.

10. Examples

See specs/ai/skill-format-examples/:

• compare-products/SKILL.md — research+extract intent, browser tool
• daily-news-digest/SKILL.md — automate intent, scheduled
• landing-page-from-brief/SKILL.md — generate-ui intent, sandbox

11. Open questions (for v1.0.0)

• Signed skills: do we adopt the kpkg signing chain or roll our own? Leaning kpkg per [[reference_blockchain_compendium]] discussion of trust roots (out of scope; tracked AIHUB-023).
• Cross-skill state: should skills be able to read each other's outputs? Probably yes via explicit chaining, no via global namespace.
• Localized skills: description.pt-BR vs separate files? Probably ICU-style i18n bundle per specs/i18n/contract.kmd.

12. References

• AIHUB-023 (registry + signed packaging)
• AIHUB-024 (Biblioteca UX)
• TOOLS-013 (this spec's authoring tool)
• TOOLS-014 (auto-mining)
• AICORE-119 (umbrella)
• Anthropic Skills documentation
• Manus Agent Skills (https://manus.im/features/agent-skills)
• policies/regression-tests.kmd
• policies/document-format.kmd
• specs/errors/user-facing-messages.kmd
• specs/multi-tenancy/contract.kmd