Artifact Instance Scoping Admin Guide

When running SkillMeat's enterprise edition, administrators can configure import policies for team and enterprise collection instances to control who can import artifacts and whether imports require review.

This guide covers: - Default permissive behavior (no policy = allow all) - Creating import policies via API and CLI - Querying effective policy for a scope - Reading the audit log - Policy precedence with RBAC - Real-world policy scenarios

Default Behavior

No policy configured means imports are allowed by default.

When a user attempts to import an artifact to a team or enterprise instance: 1. RBAC check: User must have artifact:write + collection:write scopes for that instance (required) 2. Policy check: If a policy exists for (instance_type, instance_id), evaluate it. If no policy exists, default to allow all members (permissive) 3. Audit log: Record the import attempt, outcome, and denial reason (if applicable)

This design prioritizes access — policies are opt-in constraints, not opt-out allowances.

Creating an Import Policy via API

Use the Policy CRUD endpoint to create, read, update, or delete policies.

Create a Policy

curl -X POST https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_type": "team",
    "owner_id": "team-123",
    "action": "import",
    "allow_all_members": false,
    "required_review": true
  }'

Response (201 Created):

{
  "id": "policy-456",
  "owner_type": "team",
  "owner_id": "team-123",
  "action": "import",
  "allow_all_members": false,
  "required_review": true,
  "created_at": "2026-05-20T10:30:00Z"
}

Policy fields: - owner_type: "team" or "enterprise" - owner_id: Team ID or enterprise ID - action: "import", "promote", or "deploy" (all three use the same policy evaluation) - allow_all_members: If true, any member can import (overrides required_review) - required_review: If true and allow_all_members is false, all imports require admin approval

Read Policies

List all policies:

curl -X GET https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies \
  -H "Authorization: Bearer YOUR_TOKEN"

Get a specific policy:

curl -X GET https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/policy-456 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update a Policy

curl -X PATCH https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/policy-456 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_all_members": true,
    "required_review": false
  }'

Delete a Policy

curl -X DELETE https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/policy-456 \
  -H "Authorization: Bearer YOUR_TOKEN"

Deletes the policy. Future imports to that instance revert to default (allow all).

Creating a Policy via CLI

SkillMeat provides CLI commands for managing policies.

List All Policies

skillmeat enterprise instance-policy list

Output (table):

ID         | Owner Type | Owner ID | Allow All | Required Review | Created
-----------|------------|----------|-----------|-----------------|----------
policy-456 | team       | team-123 | false     | true            | 2026-05-20
policy-789 | enterprise | org-001  | true      | false           | 2026-05-19

Create a Policy

# Team policy: require review for all imports
skillmeat enterprise instance-policy set team team-123 \
  --action import \
  --required-review

# Enterprise policy: allow all members (permissive)
skillmeat enterprise instance-policy set enterprise org-001 \
  --action import \
  --allow-all-members

# JSON output
skillmeat enterprise instance-policy set team team-123 \
  --action import \
  --required-review \
  --output json

Delete a Policy

skillmeat enterprise instance-policy delete policy-456

Confirms before deletion:

Remove policy policy-456 (team:team-123, required-review)? [y/N]

Querying Effective Policy

Determine what policy applies to a specific instance and action.

API Query

curl -X GET "https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/effective?owner_type=team&owner_id=team-123&action=import" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "allowed": true,
  "reason": "allow_all_members policy",
  "required_review": false,
  "policy_id": "policy-789"
}

or (no policy configured):

{
  "allowed": true,
  "reason": "no policy configured",
  "required_review": false,
  "policy_id": null
}

What This Tells You

• allowed: true → Imports are allowed (policy does not block them)
• required_review: true → Import proceeds to pending state, awaits admin approval
• policy_id: null → No policy found; default permissive behavior applies

Reading the Audit Log

All import, promotion, and deployment operations are recorded in the instance import audit log.

CLI: Audit Log Query

# Last 7 days (default)
skillmeat enterprise audit instance-imports

# Filter by actor (who imported)
skillmeat enterprise audit instance-imports \
  --actor alice@example.com

# Filter by target instance
skillmeat enterprise audit instance-imports \
  --target-type team \
  --target-id team-123

# Filter by action
skillmeat enterprise audit instance-imports \
  --action import

# Filter by date range
skillmeat enterprise audit instance-imports \
  --since 2026-05-01 \
  --until 2026-05-31

# JSON output for analysis/export
skillmeat enterprise audit instance-imports \
  --output json > import_audit.json

Table output:

Timestamp           | Actor          | Action | Instance Type | Instance ID | Artifact       | Status | Reason
--------------------|----------------|--------|---------------|-------------|----------------|--------|-------
2026-05-20T10:30:00 | alice@co.com   | import | team          | team-123    | my-skill       | ✓      | —
2026-05-20T10:28:15 | bob@co.com     | import | team          | team-456    | data-skill     | ✗      | Permission denied (requires team_admin role)
2026-05-20T10:15:00 | eve@co.com     | promote| enterprise    | org-001     | shared-plugin  | ✓ pending | Required review (awaiting admin approval)

Policy Precedence

When a user attempts an import, SkillMeat evaluates in this order:

1. RBAC Check (First): User must have artifact:write + collection:write scopes for the target instance
2. Fail here → import denied with reason "Permission denied"

3. Pass → proceed to policy check

4. Policy Check (Second): If a policy exists for (owner_type, owner_id, action)

5. allow_all_members: true → import allowed, proceed immediately
6. allow_all_members: false + required_review: true → import allowed but pending admin approval
7. Fail policy → import denied with reason "Import policy: required-review"

8. No policy exists → default to allow (proceed)

9. Audit: Record the attempt, outcome, and any denial reason

Implication: RBAC is a hard gate; policies are soft gates (requiring review) or informational.

Worked Examples

Example 1: Team Tightening Imports with Required Review

Scenario: Your Platform Team wants to tighten control over skill imports. New skills must be reviewed by a team lead before deployment.

Steps:

1. Create a policy:

   skillmeat enterprise instance-policy set team "Platform Team" \
     --action import \
     --required-review
   

2. Verify it's in effect:

   skillmeat enterprise audit instance-imports \
     --target-type team \
     --target-id "Platform Team" \
     --output json
   

3. When a team member imports a skill:

   skillmeat add https://github.com/org/repo/path/skill \
     --instance "Platform Team"
   

Output:

✓ Platform Team: Skill imported (status: pending review)

1. The team lead checks pending imports:

   skillmeat enterprise audit instance-imports \
     --target-type team \
     --target-id "Platform Team" \
     --action import \
     --output json | jq '.[] | select(.status == "pending")'
   

2. Team lead reviews and approves via a dedicated admin interface (UI or API).

Example 2: Enterprise Permissive + Team Restricted

Scenario: The enterprise allows all members to promote artifacts to the enterprise collection, but the Data Team restricts imports to prevent untested code.

Steps:

1. Create enterprise policy (allow all):

   skillmeat enterprise instance-policy set enterprise "org-001" \
     --action import \
     --allow-all-members
   

2. Create team policy (require review):

   skillmeat enterprise instance-policy set team "Data Team" \
     --action import \
     --required-review
   

3. Query effective policies:

   curl -X GET "https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/effective?owner_type=enterprise&owner_id=org-001&action=import" \
     -H "Authorization: Bearer YOUR_TOKEN"
   # Result: allowed: true, required_review: false
   
   curl -X GET "https://your-instance.skillmeat.cloud/api/v1/enterprise/instance-import-policies/effective?owner_type=team&owner_id=data-team&action=import" \
     -H "Authorization: Bearer YOUR_TOKEN"
   # Result: allowed: true, required_review: true
   

4. Users can freely import to enterprise, but Data Team imports are pending.

Audit Log Export for Compliance

Export the audit log to CSV for compliance reporting:

skillmeat enterprise audit instance-imports \
  --output json \
  --since 2026-01-01 \
  --until 2026-12-31 | \
  jq -r '.[] | [.timestamp, .actor, .action, .target_type, .target_id, .artifact_name, .status, .reason] | @csv' \
  > import_audit_2026.csv

Summary

Default policy: No policy = allow all (permissive).

Create a policy: API POST /api/v1/enterprise/instance-import-policies or CLI skillmeat enterprise instance-policy set.

Query effective policy: API GET .../effective?owner_type=...&owner_id=...&action=....

Read audit log: CLI skillmeat enterprise audit instance-imports with optional filters (actor, target, action, date range).

Precedence: RBAC check first (hard gate), then policy check (soft gate), then audit.

Common patterns: Team-level required-review for safety; enterprise-level allow-all for sharing.

See Also

• Artifact Instance Scoping User Guide — For users understanding imports and promotions
• Enterprise Governance Guide — Broader RBAC and instance management