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.

  • SkillsResolver discovers MODULE.entity_blueprint.skills.SKILL_ID.yml definitions across all modules (label, description, type, instructions), then runs hook_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), and CurrentEntitySkillType (bundle-specific guidance for the entity the user is on).
  • The shared YAML-discovery-plus-hook merge is extracted from BlueprintContextResolver and ManagedKeysRegistry into YamlDiscoveryTrait, reused by SkillsResolver. BundleListBuilder and CurrentEntityContext are added as composition inputs.
  • Provider-specific wiring lives in a new entity_blueprint_ai_anthropic submodule so the skill format can be tuned per provider. Its SkillListSubscriber performs a two-part injection: a ## Skills instruction block on BuildSystemPromptEvent (the obligation to check skills before acting), and a <system-reminder> skill catalog prepended to the first user message on AiAssistantPassContextToAgentEvent.
  • Ships two skill definitions: create_entity and add_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, and entity_blueprint.current_entity_context.
  • New AI tool eb_skill for loading a skill's composed guidance.
  • New extension points: the MODULE.entity_blueprint.skills.SKILL_ID.yml discovery convention, hook_entity_blueprint_skills_alter(), and the entity_blueprint.skill_type tagged service (SkillTypeInterface::compose(), tagged with type_id).
  • New submodule entity_blueprint_ai_anthropic (depends on entity_blueprint_ai, ai_agents; lifecycle: experimental), subscribing to BuildSystemPromptEvent and AiAssistantPassContextToAgentEvent. Other providers can subscribe similarly to surface skills their own way.
  • Internal refactor: BlueprintContextResolver and ManagedKeysRegistry now use YamlDiscoveryTrait; discovery behavior and three-layer precedence (universal YAML → scoped YAML → hook) are unchanged.

Comments

tim bozeman created an issue. See original summary.

  • tim bozeman committed 95dfbcee on 1.0.x
    feat: #3595055 Add Skills system: on-demand behavioral guidance for AI...
tim bozeman’s picture

Status: Reviewed & tested by the community » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.