Toolchain Skills

Compiler Tools

The compiler suite lives in skills/extensions/toolchain/. All tools accept ToolRef arguments (bare name, file path, or URI) and are hidden from agents.

skill-compile

Converts a markdown skill's prompt into a code skill for faster, deterministic execution. Accepts a single ref or multiple refs (array) — a single agent handles all files for efficiency.

Usage

agent-apps skill-compile --ref hello        # Compile one skill
agent-apps skill-compile --ref a --ref b    # Compile multiple (accumulates into refs array)

How It Works

  1. Resolve. The target must be a markdown skill (.skill.md or SKILL.md).
  2. Hash check. Computes SHA-256 of the skill source. If a cached compiled file with a matching // @generated source-hash:xxx marker exists, skip.
  3. Generate. The agent reads the skill's prompt, params, and allowed tools, then produces a .skill.js code skill that implements the same behavior. The agent decides the appropriate strategy: pure deterministic code, code with targeted ctx.manager.invoke('agent', agentArgs(prompt, returns)) for sub-tasks that require judgment, or a thin wrapper delegating to the agent.
  4. Test. Clears the tool cache and runs the skill-test tool.
  5. Iterate. If tests fail, feeds structured errors and suggestions back to the agent. Up to 3 attempts.
  6. Finalize. On success, the compiled tool shadows the source skill via path priority. On failure, removes the generated file and clears the cache.

Workspace Directory

Default: ./workspace. Mirrors source structure:

skills/greet/SKILL.md   → workspace/skills/greet/index.skill.js
skills/hello.skill.md   → workspace/skills/hello.skill.js

The workspace directory is placed first in the search path via the default config, so compiled tools shadow source skills automatically.

Source Hash

// @generated source-hash:a1b2c3d4e5f6a1b2

Files with @generated are machine-generated and may be overwritten by compile. Files without it are hand-written and are never overwritten.

skill-decompile

Generates a natural-language markdown skill from a code skill — the inverse of compilation.

agent-apps skill-decompile --ref hello
  1. Resolves the target (must be a code skill).
  2. The agent produces a .skill.md with YAML frontmatter and natural-language instructions.
  3. Saves to the workspace directory. Runs skill-test as a confidence check.
  4. Returns the output path and test results. You manually move the file to use it.

skill-test

Evaluates any tool and returns a structured result usable by both code and agents.

agent-apps skill-test --ref hello

Returns { pass, errors, warnings, suggestions, score }. The test flow:

  1. Import check (code skills) — attempts import() to catch syntax errors.
  2. Metadata check — verifies description and params presence.
  3. Unit tests (agentic, code skills) — the agent generates and runs a self-contained test script with mock context.
  4. Prompt assessment (agentic, markdown skills) — the agent evaluates prompt clarity, tool usage, and error handling.

The suggestions field enables the generate→test→improve feedback loop used by skill-compile and skill-decompile.

skill-clean

Removes all compiled artifacts. Wipes the workspace directory and clears all tool caches.

agent-apps skill-clean

skill-analyze

Analyze a skill's runtime environment — cascade metadata, available tools, directives, middleware chain, injected content. By default traces (executes with instrumentation) and interprets (agent evaluation producing findings). Pass trace: false and interpret: false for a static profile only. Works for markdown, code, and MCP skills.

agent-apps skill-analyze --ref hello                          # Full audit (trace + interpret)
agent-apps skill-analyze --ref hello --trace false --interpret false  # Static profile only
agent-apps skill-analyze --ref hello --interpret false         # Trace without agent evaluation
agent-apps skill-analyze --ref hello --elicit true            # Full audit then Q&A

skill-revise

Revise a markdown skill — improve frontmatter, description, and prose. For enriching skills with missing metadata and better instructions.

agent-apps skill-revise --ref hello

skill-introspect

Search the bundled framework documentation by keyword query, or browse all available docs. Returns relevant sections from the specification and guides. Useful for agents that need to understand framework concepts during compilation or code generation.

agent-apps skill-introspect --query "middleware ordering"
agent-apps skill-introspect                                      # list all docs
agent-apps skill-introspect --file reference/specification/events.md

skill-baseline

Run a skill on test inputs and derive testable constraints from the output. Caches constraints for validation during compilation. This is how the compiler knows what "correct" looks like for a given skill.

agent-apps skill-baseline --ref hello

skill-architect

Generate a project with skills from a natural-language description. Scaffolds a complete project structure with a main skill and supporting skills.

agent-apps skill-architect --description "A REST API for managing bookmarks"

skill-probe

Probe a skill's pipeline — run the real pipeline with execute and agent-execute replaced by capture functions. Returns the resolved cascade, chain, and execution trace without invoking the LLM. Runs in a subprocess by default for process isolation.

agent-apps skill-probe --ref hello
agent-apps skill-probe --ref hello --isolated false   # Run in-process (faster, less safe)

skill-doctor

Diagnose the Agent Apps installation, project configuration, dependencies, AWS access, and skills health. Reports structured findings with severity levels. Pass fix: true to auto-repair issues.

agent-apps skill-doctor
agent-apps skill-doctor --fix true

tutor

Interactive learning lessons for Agent Apps. Generates slide-based lessons with quizzes and animations, caches them to disk, and tracks progress in a library. Lessons cover framework concepts and are generated on demand using the agent.

agent-apps tutor                            # Open the lesson library
agent-apps tutor --unit path/to/lesson.json # Play a cached lesson directly

Ask AI