Project skills
Project skills are reusable, standards-compatible SKILL.md instruction modules that live in a project catalog. A project can acquire skills from its connected repository, another Git repository, or an upload, then assign each skill to the agents that should use it.
At run time, progressive disclosure requires a shared execution filesystem and successful materialization. Agentweaver writes instructions/resources under .agentweaver/skills/ before putting the skill's name, description, and path in the prompt. With pod-local/unavailable storage or a write failure it inlines full instructions instead; it does not emit a dangling lazy-load pointer.
Acquisition
Agentweaver recognizes one-skill-per-folder layouts under .github/skills, .copilot/skills, .claude/skills, and .agents/skills. Each skill folder must contain a SKILL.md file with YAML frontmatter for name and description, followed by an instruction body. Bundled text files in the same folder are kept as skill resources.
Acquisition is idempotent. The catalog stores a stable content hash over the name, description, instructions, and sorted resources, so re-syncing or re-importing unchanged content is a no-op. If a synced skill disappears from the connected repository, it is marked missing; if a previously valid same-source skill becomes malformed, it is marked malformed. Only active skills can be injected.
Git and raw imports pass through an SSRF guard before anything is cloned or fetched. The source parser accepts only the owner/repo shorthand, public https://github.com repo/tree/blob URLs, and raw https://raw.githubusercontent.com/.../SKILL.md URLs; every other host, scheme, non-default port, or embedded-credential form is rejected. Multi-skill sources return every discovered candidate from a preview pass so the caller selects which locations to import.
Assignment and prompt assembly
Assignments are project-scoped links between a skill and an agent name. Prompt assembly queries only active skills assigned to the current agent. Stale-folder cleanup and git-exclude maintenance are best-effort and logged when they fail. Lookup failure is also logged and yields no skill block; delivery is not a guarantee that every stale folder was removed.
Default assignment preview and apply
A confirmed active team is required before defaults can be planned. The service combines blueprint role bindings, bundled skills, the project catalog, and current assignments into a side-effect-free preview with a digest. An explicit apply recomputes that preview, compares the digest, and checks transactional store state before inserting/reactivating skills and assigning agents. Stale previews are rejected rather than partially applied. Preview itself neither acquires nor assigns skills.
Source: apps/Agentweaver.Api/Skills/SkillDefaultsService.cs:55-250.
Source
| Concern | Source |
|---|---|
| REST routes for catalog, acquisition, upload, and assignment | apps/Agentweaver.Api/Endpoints/SkillEndpoints.cs:15 |
| Catalog DTOs, idempotent upsert, missing/malformed handling, repository discovery | apps/Agentweaver.Api/Skills/SkillCatalogService.cs:16, apps/Agentweaver.Api/Skills/SkillCatalogService.cs:350 |
Import source allow-list / SSRF guard (github.com, raw.githubusercontent.com) | apps/Agentweaver.Api/Skills/SkillCatalogService.cs:772 |
SKILL.md frontmatter, recognized directories, size limits, content hash | apps/Agentweaver.Api/Skills/SkillParser.cs:33 |
| Path safety for uploads, zip extraction, and resources | apps/Agentweaver.Api/Skills/SkillPaths.cs:3 |
| Progressive-disclosure prompt block and materialization | apps/Agentweaver.Api/Skills/SkillPromptComposer.cs:8 |
| Web catalog and assignment UI | apps/web/src/pages/SkillsPage.tsx:108 |
| MCP tools | apps/Agentweaver.Mcp/Tools/SkillTools.cs:10 |
See also
Diagram details and constraints
| Element | Contract |
|---|---|
| title | Skills: catalog to safe delivery |
| takeaway | Only successful shared-filesystem writes produce pointers; all other delivery is inline. |
| group-title-0 | ACQUIRE · VALIDATE · ASSIGN |
| group-title-1 | DELIVERY BRANCHES · EXECUTION |
| Skill sources | Skill sources |
| Skill sources | Checkout · repo · marketplace |
| Skill sources | Upload and manual entry are also inputs |
| Skill sources | SkillCatalogService.cs:335-372 |
| Active assignments | Active assignments |
| Active assignments | Look up skills for this agent |
| Active assignments | No active assignments → no skill block |
| Active assignments | SkillPromptComposer.cs:45-81 |
| Project skill catalog | Project skill catalog |
| Project skill catalog | Parse / validate / content-hash upsert |
| Project skill catalog | Missing / malformed sources are tracked |
| Project skill catalog | SkillCatalogService:1045-1156 |
| Shared worktree available | Shared worktree available |
| Shared worktree available | Best-effort stale-folder cleanup |
| Shared worktree available | Attempt each assigned skill materialization |
| Shared worktree available | SkillPromptComposer.cs:63-106 |
| Explicit agent assignment | Explicit agent assignment |
| Explicit agent assignment | Catalog skills bind to agents |
| Explicit agent assignment | Delivery selects active assigned entries |
| Explicit agent assignment | SkillPromptComposer.cs:49-54 |
| Successful write only | Successful write only |
| Successful write only | Prompt metadata + SKILL.md path |
| Successful write only | Agent reads relevant skill instructions |
| Successful write only | SkillPromptComposer.cs:91-98,145 |
| Defaults preview / apply | Defaults preview / apply |
| Defaults preview / apply | Confirmed team + preview digest |
| Defaults preview / apply | Apply recomputes; stale digest rejects |
| Defaults preview / apply | SkillDefaultsService.cs:231-250 |
| Inline full instructions | Inline full instructions |
| Inline full instructions | Pod-local / unavailable filesystem |
| Inline full instructions | Also used for each failed materialization |
| Inline full instructions | SkillPromptComposer.cs:99-160 |
| Skill sources | validate |
| Project skill catalog | assign |
| Explicit agent assignment | lookup |
| Active assignments | shared FS |
| Shared worktree available | write succeeds |
| Active assignments | no FS |
| Shared worktree available | write fail |
| scope | Defaults preview has no side effects; explicit apply is digest-checked. Cleanup is best-effort. |
| groups | ACQUIRE · VALIDATE · ASSIGN; DELIVERY BRANCHES · EXECUTION |