Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

How a console command becomes AI-executable through `#[AsAiSkill]`, metadata policy, and registry discovery.

Skill Modes

Three useful ways to author skills

The important choice is not only the command name. It is the execution mode around it: read-only, mutating, or env-controlled.

#[AsCommand(name: 'seed:demo-data', description: 'Seed demo data')]
#[AsAiSkill(
    allowed: 'env::AI_ENABLE_SEED_SKILL::false',
    summary: 'Seed local demo data only when explicitly enabled.',
    riskLevel: AiRiskLevel::High,
    confirmation: AiConfirmationMode::Always,
    argumentPolicy: 'allowlisted',
    exposeArguments: ['tenant', 'force'],
)]
final class SeedDemoDataCommand extends Command {}

Mode	Typical metadata	Best for
Read-only inspect skill	Low risk + confirmation never + expose `--json`	Safe introspection commands like DI inspection, diagnostics, listings, or status checks.
Mutating maintenance skill	`Medium/high risk + confirmation always + narrow allowlist`	Operations like cache clear, reindex, snapshot rebuild, or queue maintenance.
Env-controlled skill	`allowed: 'env::AI_ENABLE_*::false'`	Commands you want available only in selected environments or temporary rollout windows.
Review pass	`bin/semitexa ai:skills --json`	Use the manifest output as the final review surface before you trust the assistant with the new skill.

#[AsAiSkill] #[AsCommand] argumentPolicy env::AI_ENABLE_*

Verified against Semitexa Ultimate 2026.09.19.1020

Adding Skills

A Semitexa AI skill is just a normal console command that also carries #[AsAiSkill] metadata. That second attribute is what makes the command discoverable and governable for the assistant.

How it works

You add #[AsAiSkill] to a real command class, choose the confirmation and argument policy that matches the command, and optionally gate the skill through .env with allowed: 'env::VAR::false' when the command should not always be exposed.

Why this matters

This keeps AI operations grounded in the same command system humans already use. Teams do not need a second hidden automation layer just for agents.

Authoring Rules

What makes a skill trustworthy

The metadata is not decorative. It defines the execution contract the assistant must stay inside.

Keep `summary`, `useWhen`, and `avoidWhen` concrete so the planner can distinguish neighboring commands.

Set `riskLevel` and `confirmation` honestly, especially for mutating or destructive actions.

Prefer `argumentPolicy: allowlisted` and expose only the options an assistant should really touch.

Use `.env` gating for commands that should not be globally visible all the time.

After adding a skill, inspect `ai:skills --json` before trusting the assistant to use it.