Company Skill Policy

Skills are how your agents pick up new abilities — and left unguarded, an agent can create, import, install, edit, or remove them at will. The company skill policy is the guardrail. It is a single per-company document that says which agents may perform which skill actions, on which skills, and from which sources.

The policy is one document per company, with a revision number for safe concurrent edits. You read it, replace it wholesale, reset it back to open, and — usefully — ask the server to explain a decision before you make a change.

Every route below is company-scoped, and company access is checked on every request. If you are new to the API, read the API Overview first for base URL, authentication, and error-code conventions; this page builds on those and won't repeat them.

The open default

A brand-new company has no stored policy at all. Reading the policy in that state gives you an open default:

{
  "schemaVersion": 1,
  "revision": 0,
  "defaultEffect": "allow",
  "rules": [],
  "materialized": false
}

The materialized flag is the one to watch. When it is false, no policy row exists — nothing has been written yet, and every skill action is allowed. Once you save a policy it becomes true and revision starts counting up from 1.

That distinction also shows up in evaluation. An unmaterialized policy short-circuits to "allowed" with the reason no_policy_default, without walking any rules.

What a policy document looks like

A policy has three parts: a schema version, a default effect, and an ordered set of rules.

Documents are strict — unknown fields are rejected.

Rules

Subjects

The subject object is a tagged union on type:

all_agents and agents only ever match agent principals. roles matches on the principal's role string, so a board principal — which evaluates with the role board — can be targeted with a roles rule.

Actions

Resource selectors

resources narrows a rule. At least one of these keys must be present, and unknown keys are rejected:

Every listed selector has to match for the rule to apply. A rule that names skillKeys will never match an evaluation that doesn't carry a skillKey.

Source locators are normalized. Both the values you store in a rule and the values you pass at evaluation time are canonicalized the same way — repo-style https URLs get a lowercased host (www.github.com becomes github.com), a lowercased owner and repo, and a stripped .git suffix. That matters: without matching normalization on both sides, a deny rule could silently never fire.

Locators are also screened for embedded credentials. A locator with a username or password in the URL, or with a query or fragment parameter that looks like token, secret, password, api_key, or authorization, is rejected with the message "Source locators must not contain credentials or secret query or fragment parameters".

Who can read and who can change

Reading the policy — and evaluating against it for yourself — needs nothing more than access to the company.

Changing it (PUT, DELETE, or evaluating on behalf of another agent) requires skill policy administration authority, which means one of:

• a board actor from the implicit local session, or an instance admin;
• a board user holding the users:manage_permissions permission in that company;
• an agent holding the users:manage_permissions permission in that company.

Anything else comes back as 403 Forbidden with code skill_policy_admin_required and the remediation "Ask a company administrator to manage the skill policy."

Two more boundaries apply to every route here:

• An unauthenticated caller gets 401 with code skill_authentication_required.
• An agent key scoped to a different company gets 403 with code skill_company_boundary_denied.

Get the Policy

GET /api/companies/{companyId}/skill-policy

Return the company's effective policy — either the stored document (with materialized: true and its current revision) or the open default described above.

Replace the Policy

PUT /api/companies/{companyId}/skill-policy

Policies are replaced wholesale, never patched. Send the complete document plus the revision you believe is current:

On success the server bumps the revision by one and returns the saved document with materialized: true.

If expectedRevision doesn't match what is stored, the write is rejected with 409 Conflict, code skill_policy_revision_conflict, and the details carry expectedRevision and currentRevision so you can re-read, re-apply your change, and retry.

A document that fails validation returns 422 Unprocessable Entity with { "error": "Invalid skill policy document" }, code skill_policy_validation_failed, and an issues array describing what went wrong.

A successful replace records a company.skill_policy_replaced activity entry against entity type company_skill_policy, with the previous and new revision, the default effect, and the rule count.

Example

curl -sS -X PUT \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/companies/{companyId}/skill-policy" \
  -d '{
    "schemaVersion": 1,
    "defaultEffect": "allow",
    "expectedRevision": 0,
    "rules": [
      {
        "id": "no-external-installs",
        "priority": 10,
        "effect": "deny",
        "subject": { "type": "all_agents" },
        "actions": ["skills.install", "skills.import"],
        "resources": { "sourceTypes": ["external_package", "git"] }
      }
    ]
  }'

Reset the Policy

DELETE /api/companies/{companyId}/skill-policy

Delete the stored policy and return to the open default. The response is the open default document (defaultEffect: "allow", no rules, materialized: false).

Resetting a company that had a policy records a company.skill_policy_reset activity entry with the previous revision and a new revision of 0. Resetting a company that never had one is a no-op and still returns the default.

Evaluate a Decision

POST /api/companies/{companyId}/skill-policy/evaluate

Ask the policy engine what it would decide, without performing the action. This is the endpoint to reach for when you want to explain a denial, or to test a rule set before relying on it.

Request body:

Without principal, the evaluation runs as you: an agent caller evaluates as its own agent (with that agent's role), and a board caller evaluates as a board principal with the role board.

With principal, you are asking about someone else — so the route requires skill policy administration authority, exactly like a write. The named agent must exist (404 Agent not found) and must belong to this company (403, code skill_company_boundary_denied).

How a decision is reached

1. If the policy isn't materialized, the answer is allow, reason no_policy_default.
2. Otherwise rules are sorted by priority ascending, ties broken by id in lexicographic order, and the first rule whose actions, subject, and resource selectors all match wins. The decision follows that rule's effect, reason explicit_rule, with the rule's id in matchedRuleId.
3. If nothing matched and defaultEffect is deny, one compatibility check runs: a principal holding a skills:create or skills:suggest-changes permission grant in the company is allowed with reason legacy_compatibility. Those grants historically authorized the whole skill mutation surface, and this preserves that scope only as a default-deny fallback — explicit rules still take precedence.
4. Otherwise the answer follows defaultEffect, reason policy_default.

The decision object

{
  "allowed": false,
  "action": "skills.install",
  "reason": "explicit_rule",
  "policyRevision": 4,
  "matchedRuleId": "no-external-installs",
  "remediation": "Contact a company administrator to change the skill policy."
}

remediation is null when the action is allowed.

Where to go next

• Agents — the agents you name in subject.agentIds and in principal.agentId.
• Activity — where company.skill_policy_replaced and company.skill_policy_reset land.
• API Overview — base URL, authentication, company scoping, and the shared error-code table.