Agent context & the skill

One of Premora’s reasons to exist is grounding coding agents in real internal context. The Premora skill gives a Claude Code / Codex agent access to your ACL-aware knowledge base, so it answers with grounded, cited facts from your own organizational knowledge instead of generic model output or hallucination.

The skill is deliberately conservative about when it engages: it reaches for Premora when org context would meaningfully improve an answer (tech stack, architecture, services, processes, people, projects, decisions, debugging with prior team knowledge), and skips it for general programming questions where Premora context is irrelevant.

Environment & tokens

The skill reads two values:

BASE  = $PREMORA_API_URL        # default: http://localhost:3001
TOKEN = $PREMORA_SKILL_TOKEN

Every request carries Authorization: Bearer $PREMORA_SKILL_TOKEN.

Minting a skill token

Skill tokens are scoped and TTL-bounded. Mint one from Settings → API Access in the Premora web UI, or via the API with a session JWT:

curl -X POST "$PREMORA_API_URL/api/user/skill/tokens" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["agent.read"],"ttlSeconds":86400}'

Scope	Grants
agent.read	Search, read wiki pages, lineage, graph, datasources, materialized views.
agent.write	The above plus: execute governed queries, save context packs / report drafts, propose wiki promotions, and post clarification requests.

This keeps every prompt, tool call, and output attributable to a user — a compliance requirement.

The retrieval workflow

The skill works iteratively, mirroring how a careful engineer narrows in on context:

1. Search — GET /api/user/skill/search?q=<query>&limit=8 → ranked wiki pages/chunks. Take the slug of the top results.
2. Read — GET /api/user/skill/wiki/<slug> → full page content.
3. Lineage — GET /api/user/skill/wiki/<slug>/lineage → which raw sources contributed.
4. Graph — GET /api/user/skill/graph/neighborhood?slug=<slug>&depth=1&limit=20 → related pages, to discover adjacent topics.

If the agent would otherwise guess or caveat an answer, it searches again instead — the cost of an extra retrieval round is lower than the cost of a wrong implementation.

Clarification queue

When a gap can’t be resolved from the wiki because the knowledge hasn’t been captured yet, the agent can queue a clarification request rather than guessing or interrupting the developer mid-task (requires agent.write):

POST /api/user/skill/clarification-requests
{
  "question": "string",      # what the agent needs to know
  "context":  "string",      # why it matters / what it's blocking
  "blockedOn": ["slug"]      # wiki slugs that can't be finalized without this answer
}

The request is queued asynchronously; the developer answers from the pending-questions panel when convenient. Answered clarifications become searchable wiki content.

Governed data & durable knowledge (agent.write)

• List datasources — GET /api/user/skill/datasources before any query.
• Governed query — POST /api/user/skill/query-runs with a natural-language prompt (never raw SQL); Premora translates it to SQL against an approved semantic model and runs it read-only.
• Materialized views — GET /api/user/skill/materialized-views → curated, pre-filtered knowledge scopes.
• Context packs — POST /api/user/skill/context-packs saves a useful research turn.
• Wiki promotions — POST /api/user/skill/wiki-promotions proposes synthesized content for the team wiki, as a draft under review.

Quick start

1. Mint an agent.read token from Settings → API Access.
2. Export PREMORA_API_URL and PREMORA_SKILL_TOKEN in your agent’s environment.
3. Install the Premora skill package and let the agent query during AI-assisted coding.

Skill vs. model endpoint

The skill described here feeds the agent your governed knowledge. Separately, Premora can be the agent’s private model endpoint (OpenAI- or Anthropic-compatible) — see Connect a coding agent. Use both together: a private model and grounded, cited company context.