Skip to content

feat(templates): declare skills-library skills to assign at creation (#4387) - #4388

Merged
vybe merged 5 commits into
Abilityai:devfrom
francisjervis:feature/4387-template-library-skills
Nov 19, 2026
Merged

vybe merged 5 commits into
Abilityai:devfrom
francisjervis:feature/4387-template-library-skills

Conversation

@francisjervis

@francisjervis francisjervis commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Closes #4387

Journey Impact: extends: J18

What

template.yaml can now declare skills from the platform skills library that an agent created from the template should hold:

library_skills:
  - plan-interview-research
  - user-research

At creation (local:, github: and copy-snapshot templates), each declared name the library has is assigned to the new agent (assigned_by = owner, assigned_by_agent = the creating agent, if any). Once the agent's /health answers, the start-path injection delivers them.

Why

template.yaml's skills: field is documentation only, and the create path never assigned library skills. A template built around a library source (a research agent and its skills source, in the case that prompted this) was created without its core skills, and the owner had to assign them by hand. Bundling copies into the template freezes them and cuts them off from library updates.

Creation also starts the container directly, not through start_agent_internal, so even a skill assigned right after creation was not delivered until the agent's next start.

How

  • services/template_skills.py: a total reader, the shape of template_plugins / template_schedules (never raises; charset from skill_packaging.SKILL_NAME_RE, de-duplicated, capped at 50, set:<name> refused with a named error). Both catalog builders surface library_skills + library_skill_errors.
  • _TemplateResolution.declared_library_skills, filled by all three resolver branches (not template_data, which is {} on github:).
  • create_agent_internal passes the declaration through _permitted_library_skills: the §21.3.1 skills.manage fence via dependencies.capability_refusal, all-or-none and non-raising. An agent key without the grant gets no assignment, so creating an agent from a template can't be used to obtain library skills. A refusal writes a capability_refused audit row (target = the new agent); an agent key the grant admits writes capability_used, as at the route fence. dependencies._audit_capability now tolerates request=None (system deploy).
  • _materialize_agent_files assigns each name the library has (db.assign_skill; unknown names skipped and logged), then spawns a fire-and-forget task that waits on lifecycle.wait_for_agent_ready (LIBRARY_SKILLS_READY_TIMEOUT_S, a 900 s constant) and runs lifecycle.inject_assigned_skills, so sets, gates and the prune behave as on a start.
  • Ghost-skipped. Non-fatal inside the creation rollback fence. A missed delivery is repaired by the next start, since the rows are already stored.

Relationship to skill_assignment_service.assign_and_deliver (ent#1030): that helper delivers immediately, which at creation time would only report not_delivered because the agent server is not up yet. This path writes the rows at creation and defers delivery to the start-path injection once the agent is ready (that injection reconciles library gates before delivering). Happy to route the post-readiness step through assign_and_deliver instead if you'd rather keep a single sequence, which would also add the skills_changed broadcast.

Docs

Requirements §21.3.4 (requirements/skills.md), the Architecture Map row and a section in architecture/agent-lifecycle.md for the new module, the template.yaml reference in TRINITY_COMPATIBLE_AGENT_GUIDE.md, the feature flow feature-flows/template-library-skills.md (indexed), and a "Declared Library Skills" section in user-docs/agents/creating-agents.md.

Testing

  • tests/unit/test_4387_template_library_skills.py: 45 tests covering the reader's shapes, both catalog builders, all three resolver branches (copy snapshot included), the fence and its audit rows (person / user / system pass; agent key without the grant, connector and no-scope refused; the real audit writer with request=None), assignment (owner attribution, creating-agent attribution, unknown names skipped, ghost skip, non-fatal), and delivery (readiness-gated, failure swallowed, no-loop spawn).
  • tests/unit/test_1484_create_agent_characterization.py (test_4387_*, 3 tests): a whole create_agent_internal run pins the call site. A person gets the names; an agent key without the grant gets none plus a refusal row; an agent key with the grant gets them, attributed to itself.
  • Mutation: passing tr.declared_library_skills unfenced at the call site turns test_4387_an_agent_key_without_skills_manage_gets_none red; dropping the copy-snapshot assignment turns test_copy_snapshot_branch_populates_declared_library_skills red.
  • Related suites on this branch (80 files: templates, create path, skills, plugins, schedules, metrics, architecture guards): 2508 passed. After the review fixes: 65 files (create path, templates, skills, every capability-audit suite) 2423 passed, and 30 doc/architecture guard files 910 passed. The 8 failures are in test_ent1030_skills.py and fail identically on dev without this change when run in the same set; the file passes on its own (24/24) and alongside the new tests in either order.
  • End to end on a local instance: created an agent from a local: template declaring 4 library skills. All 4 were assigned at creation and delivered after the agent became ready ([§21.3.4] Delivered library skills to …: success).

🤖 Generated with Claude Code

…bilityai#4387)

A template can now name skills from the platform skills library in
`template.yaml` `library_skills:`. Creating an agent from it assigns each
name the library has (as the owner; the creating agent recorded for
attribution) and delivers them once the agent's /health answers, through
the start-path injection. Creation starts the container directly, so
nothing else delivered assigned skills before the agent's next start.

- services/template_skills.py: total reader (charset from skill_packaging,
  de-dup, cap 50, `set:` refused by name); both catalog builders surface
  library_skills + library_skill_errors
- all three resolver branches fill _TemplateResolution.declared_library_skills
- the skills.manage fence applies at creation: an agent key without the
  grant gets no assignment; people, user keys and the system key pass
- ghost-skipped, non-fatal inside the creation rollback fence; a missed
  delivery is repaired by the next start
- requirements §21.3.4, architecture map + agent-lifecycle section, agent guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vybe

vybe commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Thanks for this — the gap is real: a single agent created from a template gets no library skills today, only system manifests assign them.

We'd like to take it, with one change before review:

  • Accept skill sets. Sets are a shipped unit of assignment, so set:<name> should be assigned rather than refused with a named error.
  • Speak the manifest's language. A system manifest member already declares skills and skill_sets (src/backend/services/system_service.py). Please align the template field(s) with that shape — for example library_skills + library_skill_sets, or one list that takes both forms with the same parsing — so a template and a manifest member read the same way.

Everything else in the design (the skills.manage fence, ephemeral agents skipped, creation never rolled back, delivery through the start-path injection) looks right. Once that's in, it goes through the normal PR validation. I've moved #4387 to ready.

@vybe

vybe commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

merge-train 2026-11-10: ejected. Rides the next train once fixed.

The feature looks right and all 6 acceptance criteria map to code. These items keep it off this train:

  1. The skills.manage fence's call site is not pinned by a test (crud.py ~4164, declared_library_skills=_permitted_library_skills(current_user, ...)). If the call site passes tr.declared_library_skills unfenced, all 43 tests in test_4387_template_library_skills.py stay green. An agent key without skills.manage would then get library skills by creating an agent. Please add a test that drives create_agent_internal. The snapshot-branch assignment (crud.py ~1926) is unpinned in the same way.
  2. A third-party name is in public docs. docs/memory/requirements/skills.md §21.3.4 names a specific research agent and its skills repo, and the fixtures use deutero-setup. Please use the generic wording from the PR body ("a research agent and its skills source").
  3. LIBRARY_SKILLS_READY_TIMEOUT_S is read from the environment but not wired into docker-compose*.yml or .env.example. Either wire it in or make it a constant.
  4. Smaller items: no feature-flow doc, no user-docs entry, the fence refusal at creation is a log line rather than an audit row, and the Journey Impact line is missing.

Tier 1 has also never run on this fork PR, since its workflows are waiting at action_required.

@vybe vybe added the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 10, 2026
…refusal (Abilityai#4387)

Addresses the merge-train review on Abilityai#4388.

- Call site pinned: three test_4387_* cases in the create-agent
  characterization suite run a whole create_agent_internal. With the call
  site passing tr.declared_library_skills unfenced, the agent-key case goes
  red. The copy-snapshot resolver branch gets its own test as well.
- The fence refusal at creation is now an audit row (capability_refused,
  target = the new agent), and an agent key the grant admits leaves a
  capability_used row, like the route fence. dependencies._audit_capability
  now tolerates request=None, which a system deploy passes.
- LIBRARY_SKILLS_READY_TIMEOUT_S is a constant, not an env read.
- Third-party names removed from the requirement text and test fixtures.
- Feature-flow doc (template-library-skills.md) and a "Declared Library
  Skills" section in the creating-agents user doc.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@francisjervis

Copy link
Copy Markdown
Contributor Author

Thanks for the review. All four items are addressed in de068e9.

  1. Fence call site pinned. Three test_4387_* cases in test_1484_create_agent_characterization.py run a whole create_agent_internal from a local: template that declares library_skills:

    • a person gets the names;
    • an agent key without skills.manage gets [] and a capability_refused row;
    • an agent key with the grant gets the names, with assigned_by_agent set to itself.

    Passing tr.declared_library_skills unfenced at the call site makes the agent-key case fail. The copy-snapshot resolver branch has its own test (test_copy_snapshot_branch_populates_declared_library_skills), which fails if that branch's assignment is removed.

  2. Third-party name removed. §21.3.4 now says "a research agent and its skills source", and the fixtures and guide example use generic skill names.

  3. LIBRARY_SKILLS_READY_TIMEOUT_S is a constant (900 s), with no env read.

  4. Smaller items:

    • The refusal at creation is now an audit row (capability_refused, target = the new agent, declared names in details), and an admitted agent key writes capability_used, the same as the route fence. To support the system-deploy path, dependencies._audit_capability now accepts request=None (same getattr pattern as template_source_policy.audit_refusal). A test covers the real writer with no request.
    • New feature flow feature-flows/template-library-skills.md, indexed.
    • User docs: a "Declared Library Skills" section in user-docs/agents/creating-agents.md.
    • Journey Impact: extends: J18 added to the description.

Tests: 65 related files (create path, templates, skills, every capability-audit suite) gave 2423 passed. The same 8 test_ent1030_skills.py failures as on dev show up only when the whole set runs together; that file passes alone and paired with the new tests in either order. The 30 doc and architecture guard files gave 910 passed.

Tier 1 still needs a maintainer to approve the workflow runs on this fork PR.

Conflicts in docs/memory/feature-flows.md and agent_service/crud.py were
keep-both: dev's declared_model seed (Abilityai#4442) and bundled avatar install
(ent#1173) sit beside this branch's declared_library_skills.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vybe vybe removed the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 19, 2026
@vybe

vybe commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Merged current dev into this branch (c6b15aaf2) so it stops conflicting. Two files conflicted, both keep-both: docs/memory/feature-flows.md (index rows) and agent_service/crud.py, where dev's declared_model seed (#4442) and bundled-avatar install now sit beside your declared_library_skills. test_4387_template_library_skills.py, test_1484_create_agent_characterization.py and test_4442_* pass on the merged tree (188 passed). I also approved the workflow runs, so Tier 1 runs on this PR for the first time, and lifted status-needs-fix since your 11-11 push answered the 11-10 items. It goes through validation on the next merge train.

…gnment (Abilityai#4387)

dev's ent#753 guard requires every agent_skills writer to reach the gate
reconcile. The creation-time writer now does, before delivery, and is
listed in the guard's expected sites.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vybe

vybe commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

One more push from me (2bac52c18), because the dev merge surfaced a new failure in regression diff: test_ent753_assignment_hooks::test_every_assignment_writer_reaches_the_gate_reconcile. That guard landed on dev after this branch started and requires every agent_skills writer to reconcile the agent's skill gates.

_assign_declared_library_skills is now async and calls skill_gate_map_service.reconcile_library_gates after its writes, before delivery is spawned, and the site is added to the guard's EXPECTED_SITES. The guard, test_4387_template_library_skills.py, test_1484_create_agent_characterization.py and the three neighbouring _materialize_agent_files suites pass (209 passed). @francisjervis please pull before pushing anything further.

…incipal (Abilityai#4387)

The assignment-time gate reconcile carried no actor, so a default gate
applied at creation was audited as system. The principal and request are
now threaded through, a test pins the reconcile and its order before
delivery, and an ephemeral creation no longer runs the skills.manage
fence it cannot use.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vybe

vybe commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

merge-train (2026-11-19): validated at 2bac52c18 at full depth, with no critical findings. All four 11-10 items are closed: the unfenced call site and the removed copy-snapshot assignment each turn a test red, and nine mutations in all were caught. The dev merge lost and duplicated nothing, and _audit_capability(request=None) weakens no existing caller.

Ruling on skill sets: names-only ships now. The 11-10 request for set:<name> and the manifest's skills / skill_sets shape moves to #4662, recorded on #4387.

One more commit from me on this branch (49d3dcee8), for what validation found in the gate reconcile I added earlier today and around it:

  • The reconcile ran with no actor, so a default gate applied at creation was audited as system. create_agent_internal now passes the creating principal and the request down (two keyword-only parameters with None defaults on _materialize_agent_files and _assign_declared_library_skills), and the context is built the way skill_assignment_service.sync_gates builds it.
  • Only the AST guard pinned the reconcile. Three tests in test_4387_template_library_skills.py now use a library skill marked approval: recommended against the real reconcile and assert the gate row exists, set by the creator, at the moment delivery is spawned.
  • An ephemeral creation ran the skills.manage fence and left a capability_refused or capability_used row for a capability that could not apply. The fence is skipped for an ephemeral agent, with a test through the whole create_agent_internal.
  • Docs: template-library-skills.md and the Templates can declare skills-library skills to assign at creation (library_skills:) #4387 paragraph in agent-lifecycle.md now describe the reconcile step.

292 tests across the nine suites that touch these functions pass. @francisjervis please pull before pushing anything further. Left for follow-up, none blocking: the create dialog does not show a template's declared skills, there is no skills_changed broadcast after the deferred delivery, and the create response does not tell an agent caller its declared skills were refused.

@vybe vybe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merge-train (2026-11-19): validated at 49d3dce; batch green on #4667.

@vybe
vybe merged commit 00b1e5a into Abilityai:dev Nov 19, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants