FAQ

Note: the @sidianlabs/policy CLI is not published to npm yet — run it from a clone (npm install && npm run build, then node bin/policy.js).

Is POLICY.md a replacement for SKILL.md?

No - the counterpart. SKILL.md teaches abilities ("here is an ability you can use"). POLICY.md enforces boundaries ("here is a boundary you must respect"). Ship them side by side: the skill directory holds both files.

Do agents have to support POLICY.md, or is it enforced externally?

Both paths work. An agent can read the Markdown body as system context (soft enforcement), while a runtime engine enforces the frontmatter rules deterministically (hard enforcement). The strongest setup does both: the agent understands the boundary, the engine guarantees it.

What happens when project and skill policies conflict?

Most-severe-wins across the composite engine: deny beats require_approval beats allow. A skill-local deny always overrides a project-level allow. Design skill policies as narrow exceptions, project policies as broad baselines.

validate passes but the agent still misbehaves. Why?

Validation checks schema, operators, and YAML - not intent coverage. Common gaps: the capability pattern doesn't match the actual capability string (check list output), a missing condition makes the rule match everything (or nothing, if inverted), or the policy file isn't in a discovered location (see File Format).

How do I share policies across repos?

npx @sidianlabs/policy install owner/repo --dest=.policies

Publish guardrails as a repo, install by owner/repo. Version them with the version field and pin installs per project.

Can I use POLICY.md with OpenAI Codex?

Yes - export to both Codex formats:

import { toCodexExecpolicy, toCodexGuardianPrompt } from '@sidianlabs/policy/adapters/codex';

toCodexExecpolicy emits Starlark for the Codex runtime; toCodexGuardianPrompt emits Guardian prompt text for the harness.

How do I keep AGENTS.md in sync?

npx @sidianlabs/policy sync

Regenerates the <policy_system priority="1"> block from current policies. Run it in CI so the block never drifts from the files.

Allowlist or denylist?

Both, layered: broad allow baselines at project scope, narrow deny rules for known-dangerous capabilities (secret writes, destructive commands, direct pushes to main), and require_approval for the gray zone (new dependencies, infra changes, large payments). Priority (priority field, higher wins) breaks ties explicitly instead of relying on file order.