Introspection — Making Skills Discoverable

The toolchain (skill-compile, skill-decompile, skill-revise, skill-architect, skill-analyze, skill-test, skill-baseline, skill-introspect) understands any skill's runtime environment through introspection. This document describes the practices that make skills self-documenting so these tools work without hardcoded knowledge.

Principle: The Skill Is the Documentation

The toolchain learns about a skill from four sources, in priority order:

1. The skill's own frontmatter — name, description, params, returns, tags, allowedTools, metadata.
2. The cascade — metadata inherited from the authority and base chain, merged per annotation rules ($merge, $private/$public, $dynamic/$static, $remove, $order).
3. Middleware frontmatter — every metadata key that resolves to a tool with role: middleware triggers that tool in the pipeline. The middleware tool's own schema and description explain what it does to the skill's runtime environment.
4. Framework docs — searched via skill-introspect when schemas alone aren't enough.

If a skill's frontmatter and its middleware's frontmatter are complete, the toolchain handles it with zero special-case logic. New patterns work automatically as long as the middleware tools describe themselves.

Rich Schemas

JSON Schema supports description on every property, examples, default, and enum. Use these — the generation agents read them via tool listings.

Property descriptions should explain behavior, not restate the type:

params:
  type: object
  properties:
    ref:
      type: string
      description: "Skill name or file path to analyze"

When a tool's behavior isn't obvious from the type, add examples:

properties: {
  path: {
    type: "string",
    description: "File path relative to project root. Returns content as a raw string — parse JSON/YAML yourself.",
    examples: ["data.json", "config/settings.yaml"]
  }
}

Always declare returns when the output shape matters — the toolchain uses it for code generation and the test system uses it for structural validation.

Some schema properties are internal plumbing — callback refs, wiring args, or fields passed programmatically that agents shouldn't use directly. Mark these with a description that says so:

properties: {
  onMessage: {
    type: "string",
    description: "Internal — callback ref passed programmatically, not for direct use"
  }
}

The agent reads property descriptions during discovery and will avoid properties marked this way.

Schemas share the context window with conversation history, tool listings, and skill prose. Add high-impact detail. Don't add boilerplate that restates the type.

Middleware Self-Documentation

Middleware is discovered by role: middleware — not by naming conventions. Any tool with this role that appears as a metadata key in the cascade is recognized as active middleware.

A middleware tool's schema describes what the metadata key accepts. But middleware often transforms the skill's runtime environment — injecting args, setting defaults, enriching prompts. The schema description should explain these effects:

params: {
  type: "object",
  description: "Configure this middleware. Skills with this key active receive modified args/context as described.",
  properties: {
    profile: { type: "string", description: "Which configuration profile to use" },
    timeout: { type: "number", description: "Override the default timeout in milliseconds" }
  }
}

When skill-analyze sees a middleware key in a skill's cascade metadata, it reads that middleware tool's schema and learns the full contract — what the skill receives and what it should return. This applies to any middleware that transforms the environment. All are self-documenting through the same mechanism.

The Cascade

skill-analyze resolves the full cascade for a skill, applying all annotation types:

• $merge — controls how parent and child values combine
• $private / $public — controls which keys propagate to children
• $dynamic / $static — controls which keys trigger middleware vs remain data
• $remove — removes keys from the merged result
• $order — controls middleware execution order

The cascade result tells the toolchain which middleware is active on a skill and what data keys are available.

Outward Context

skill-analyze provides situational awareness beyond the skill itself:

• Sibling skills — other non-library skills visible from the search paths, with name, description, type (markdown/code), and metadata keys present. This lets generation agents understand the project structure without scanning the filesystem.
• Project files — non-skill files in the project root (assets, configs, docs, stylesheets). Directories matching { ignore } entries in the search paths are skipped.

Generation agents use this context to understand what resources exist in the project — shared modules, static assets, documentation — and can use file-read or skill-describe to investigate further when needed.

skill-introspect

Semantic search and file browsing for framework documentation, skills, and runtime source. Behavior determined by args:

• query — semantic search via pre-built embeddings (Cohere Embed v4). Returns the most relevant chunks across docs, skills, and src. Add file to search within a specific file.
• file (no query) — return file contents, with optional start_line/end_line for line ranges.
• neither — list all indexed files (table of contents).

The embeddings index is built at npm run build time (or npm run index standalone). It covers docs/, skills/, and src/.

Agent-Driven Discovery

Generation skills (compile, decompile, revise, architect) are agent-driven. Each agent has access to discovery tools and can explore the framework at runtime:

The compile agent also has file-write to produce the compiled output.

All generation agents support elicit mode — when enabled, the agent can use gateway-send and gateway-receive to ask the user for help when stuck.

The pre-loaded context from skill-analyze is the seed. The discovery tools are the self-discover mechanism. The agent explores further when the seed isn't enough — reading sibling skills, checking middleware params, looking up framework docs.

Core Concepts

All framework knowledge available to generation agents comes from two sources:

1. docs/discovery/core-concepts.md — loaded at runtime by the toolchain. Contains the essential framework facts: skill formats, frontmatter structure, the cascade, tool resolution. This is the single source of truth for hardcoded knowledge. Edit this file to update what agents know about the framework.
2. Self-discovery — everything else comes from skill-list, skill-describe, skill-introspect, and file-read at runtime. No domain-specific patterns are hardcoded in the toolchain.

Optional prompt sections are appended based on the task:

• Compiled Format — ESM module structure, source-hash caching, template literal safety. Used by compile and architect.
• Self-Discovery — the explore-first workflow with example invocations. Used by architect.
• Skill Writing Guide — prose quality principles for markdown skills. Used by decompile, revise, and architect.

How the Toolchain Uses All This

skill-analyze resolves the cascade, discovers active middleware via role: middleware, reads their schemas, gathers tool context from allowed-tools, searches docs for additional context, and collects outward context (sibling skills, project files).

skill-compile pre-loads the analysis, then hands control to an agent with discovery tools. The agent reads the source skill, explores siblings and project files as needed, writes a JS module, and validates it with skill-test. If validation fails, the retry loop feeds errors back and the agent fixes them.

skill-decompile analyzes the code skill, then hands control to an agent that writes a markdown skill capturing the same behavior. The agent can explore framework docs to understand middleware effects.

skill-revise discovers which metadata keys are missing, analyzes the skill, then hands control to an agent that infers frontmatter and (by default) rewrites the prose body. Use frontmatterOnly to restrict to metadata inference only.

skill-architect hands control to an agent that explores available middleware via skill-list, designs a project plan, writes each skill file, and validates each with skill-test. Interactive mode presents the plan for review before generating files.

skill-test validates skills through tiered checks: parse/import → structural → constraint → assertion → AI judge. Evaluation agents (assertion grading, AI judge) use no tools — pure reasoning.

skill-baseline runs a skill on synthetic inputs, captures the output, and derives deterministic constraints. These constraints are used by compile and revise (with live mode) to verify behavioral equivalence.

No step requires hardcoded knowledge about specific patterns. New middleware, new runtime features — they work automatically as long as the tools describe themselves through their frontmatter.

See Also

• Specification — Complete technical reference
• Core Concepts — Bootstrap framework knowledge for agents
• Skills Reference — All bundled skills organized by category
• Cookbook — User-facing guide