PaperClipAI/maps/agent-access-map/skills.md

Skill discovery, authoring, and policy — agent access

Product map: Skill discovery, authoring, and policy.

Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b. Native REST transport reconciled in this change; see the shared transport contract.

This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.

discovery

Review: baseline.

API: present — representative operation IDs:

• GET /api/companies/{companyId}/skills.
• POST /api/companies/{companyId}/skills/import.

Agent access: available — REST / native call_api / CLI skills and sources.

Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Installation/import is governed by company skill policy, not inferred from an agent's role name.

authoring

Review: baseline.

API: present — representative operation IDs:

• POST /api/companies/{companyId}/skills.
• PATCH /api/companies/{companyId}/skills/{skillId}/files.

Agent access: available — Native create_skill/update_skill for single-file operations; REST for other files/metadata.

Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Writable/fork policy and expected version apply. Native helpers intentionally support a narrower shape than full API.

versions

Review: baseline.

API: present — representative operation IDs:

• GET /api/companies/{companyId}/skills/{skillId}/versions.

Agent access: available — REST / native call_api / CLI skills.

Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Revision metadata has an API; pinned execution skill versions and installed latest are distinct.

policy

Review: baseline.

API: present — representative operation IDs:

• PUT /api/companies/{companyId}/skill-policy.
• POST /api/agents/{id}/skills/sync.

Agent access: partial — REST / native call_api under users:manage_permissions or target configuration policy.

Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Policy administration has an explicit agent grant branch; assigning agent skills also checks the target's config authority.

testing

Review: baseline.

API: present — representative operation IDs:

• POST /api/companies/{companyId}/skills/{skillId}/test-runs.

Agent access: available — Permitted agent REST / native call_api creation, control and history; no dedicated CLI test command found.

Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: No dedicated native orchestration binding; generic REST calls retain skills.test policy, task-assignment authorization, responsible-user intersection and admitted skill-test JWT scope.