Documentation / @agentick/core / SkillDef

Interface: SkillDef<TInput>

Defined in: core/src/skill/skill.ts:104

Definition of a callable skill. Mirrors the Agent Skills frontmatter spec, with optional Agentick-specific extensions.

Type Parameters

TInput

TInput = unknown

Type of the args object. Defaults to unknown for skills loaded from files where the input shape isn't declared.

Properties

allowedTools?

readonly optional allowedTools: (string | ExecutableTool<(input, ctx?) => ContentBlock[] | Promise<ContentBlock[]>>)[]

Defined in: core/src/skill/skill.ts:199

Tools the skill is allowed to use during execution. Maps to spec field allowed-tools. String entries are tool names resolved against the session's tool registry at execution time; ExecutableTool entries are used directly.

argumentHint?

readonly optional argumentHint: string

Defined in: core/src/skill/skill.ts:166

Hint shown during autocomplete to indicate expected arguments (e.g. [issue-number]). Claude Code extension (argument-hint).

argumentNames?

readonly optional argumentNames: string[]

Defined in: core/src/skill/skill.ts:190

Names of positional arguments, in order. From the spec's arguments frontmatter field. Enables $0/$1/... and $name substitution.

For typed object args, the values at these names are looked up by key; the order also defines positional access ($0 = first, etc.).

compatibility?

readonly optional compatibility: string

Defined in: core/src/skill/skill.ts:139

Environment requirements (intended product, system packages, network access, etc.). ≤500 chars. Most skills omit this.

Example: Requires git, docker, jq, and access to the internet.

description

readonly description: string

Defined in: core/src/skill/skill.ts:123

What the skill does and when to use it. Required by the open Agent Skills spec (and by defineSkill). ≤1024 characters. Surfaced to the model in skill listings to help it decide when to apply the skill automatically.

disableModelInvocation?

readonly optional disableModelInvocation: boolean

Defined in: core/src/skill/skill.ts:208

When true, the model cannot auto-invoke this skill — only explicit programmatic / user invocation. Maps to disable-model-invocation. NOTE: captured but not enforced in Phase 2; gating belongs with the skill registry (Phase 3+).

input?

readonly optional input: ZodSchema<TInput>

Defined in: core/src/skill/skill.ts:181

Optional Zod schema for the args object. Validated at invocation if provided. Omit to accept any args.

instructions

readonly instructions: string

Defined in: core/src/skill/skill.ts:174

Skill instructions — the markdown body of SKILL.md. May contain $ARGUMENTS, $N, $name, ${VARS} substitutions resolved at invocation time.

license?

readonly optional license: string

Defined in: core/src/skill/skill.ts:131

License applied to the skill. Spec recommends keeping it short — the name of a license, or the name of a bundled license file (e.g. Apache-2.0, Proprietary. LICENSE.txt has complete terms).

maxTicks?

readonly optional maxTicks: number

Defined in: core/src/skill/skill.ts:220

Maximum ticks the skill loop may run. Default 10.

metadata?

readonly optional metadata: Record<string, string>

Defined in: core/src/skill/skill.ts:153

Arbitrary metadata mapping (string keys to string values, per spec). Use for additional properties not covered by the standard fields. Reasonably-unique keys avoid collisions across tools.

Example:

yaml

metadata:
  author: example-org
  version: "1.0"

name

readonly name: string

Defined in: core/src/skill/skill.ts:115

Skill name. Strict spec format: 1–64 characters, lowercase alphanumeric and hyphens only, no leading/trailing or consecutive hyphens. For folder-loaded skills must match the parent directory name (validated by the loader).

Examples: pdf-processing, code-review, triage-issues. Invalid: PDF-Processing, pdf--processing, -pdf, pdf_proc.

skillDir?

readonly optional skillDir: string

Defined in: core/src/skill/skill.ts:229

Absolute path to the directory containing SKILL.md. Set by the loader; supports ${AGENTICK_SKILL_DIR} substitution and lets skill authors reference supporting files (templates, examples, scripts) in the same directory.

userInvocable?

readonly optional userInvocable: boolean

Defined in: core/src/skill/skill.ts:214

When false, the skill is hidden from user-facing listings. Maps to user-invocable. Captured; enforcement is registry-side (later).

whenToUse?

readonly optional whenToUse: string

Defined in: core/src/skill/skill.ts:160

Additional invocation hints — example phrases / triggers. Appended to description for selection. Claude Code extension (when_to_use).

knob

Functions