Problem/Motivation
Behavioral guidance for AI agents (how to compose a page, what workflow to follow before creating an entity, how to fit a new section into an existing layout) was carried in the system prompt. As a system prompt grows, individual instructions become less salient and the model loses awareness of them, and every conversation pays the token cost of guidance it may never use. Guidance should arrive only when the task at hand actually calls for it.
Proposed resolution
Add a skills system: named bundles of behavioral guidance the AI loads on demand. The conversation carries only a catalog (skill id + description); the full instructions arrive through the eb_skill tool when a skill matches the task. This mirrors how Claude Code surfaces skills.
SkillsResolverdiscoversMODULE.entity_blueprint.skills.SKILL_ID.ymldefinitions across all modules (label, description, type, instructions), then runshook_entity_blueprint_skills_alter(). Cached.SkillTypeManager— a tagged service collector (entity_blueprint.skill_type) whose plugins compose a skill's response from its definition plus invocation parameters:DefaultSkillType(verbatim),CreateEntitySkillType(visible bundle catalog + a blocking pick-bundle/read-schema/plan checklist), andCurrentEntitySkillType(bundle-specific guidance for the entity the user is on).- The shared YAML-discovery-plus-hook merge is extracted from
BlueprintContextResolverandManagedKeysRegistryintoYamlDiscoveryTrait, reused bySkillsResolver.BundleListBuilderandCurrentEntityContextare added as composition inputs. - Provider-specific wiring lives in a new
entity_blueprint_ai_anthropicsubmodule so the skill format can be tuned per provider. ItsSkillListSubscriberperforms a two-part injection: a## Skillsinstruction block onBuildSystemPromptEvent(the obligation to check skills before acting), and a<system-reminder>skill catalog prepended to the first user message onAiAssistantPassContextToAgentEvent. - Ships two skill definitions:
create_entityandadd_section.
API changes
- New services:
entity_blueprint.skills_resolver(SkillsResolverInterface),entity_blueprint.skill_type_manager, the three skill-type services,entity_blueprint.bundle_list_builder, andentity_blueprint.current_entity_context. - New AI tool
eb_skillfor loading a skill's composed guidance. - New extension points: the
MODULE.entity_blueprint.skills.SKILL_ID.ymldiscovery convention,hook_entity_blueprint_skills_alter(), and theentity_blueprint.skill_typetagged service (SkillTypeInterface::compose(), tagged withtype_id). - New submodule
entity_blueprint_ai_anthropic(depends onentity_blueprint_ai,ai_agents;lifecycle: experimental), subscribing toBuildSystemPromptEventandAiAssistantPassContextToAgentEvent. Other providers can subscribe similarly to surface skills their own way. - Internal refactor:
BlueprintContextResolverandManagedKeysRegistrynow useYamlDiscoveryTrait; discovery behavior and three-layer precedence (universal YAML → scoped YAML → hook) are unchanged.
Comments
Comment #3
tim bozeman commented