Be Civic Specs
becivic.be

Be Civic — Skill-Drafting Protocol

Canonical system specifications for the Be Civic project.

Be Civic — Skill-Drafting Protocol

This sub-spec covers everything related to authoring and operating skills: the skill-drafting protocol for new skills and amendments (§15.1–§15.6), harness consumer obligations (§15.7), skill body discipline for customer-facing content (§15.8), and OSS-alignment frontmatter (§15.9).

The actual skill schema — frontmatter fields, status enum, composition rules — lives in schemas.md §6.1. The lifecycle that advances drafted skills from draft → alpha → beta → stable lives in lifecycle.md §9. PII scrub obligations on harness implementations are specified in privacy.md §8.

15. Skill-drafting protocol

Designing a skill is itself a skill — a process with steps, sources, and stopping criteria. Drafting agents that wing it produce thin or wrong skills and waste tokens on undirected web research. The drafting protocol is embodied as two meta-skills (per G.11):

  • meta-draft-l1-skill (category: meta) — drafting walkthrough; consumer AI invokes when extending corpus; produces a draft (target_type=skill) submission — pre-2026-05-15 named skill_draft
  • meta-decompose-process (category: meta) — sub-skill extraction utility; invoked from meta-draft-l1-skill step 6

Plus two prose entry pages:

  • index.mdx — landing page consumed by the renderer; the human landing at becivic.be/ is served from this file via the renderer Worker
  • agents.mdx — agent entry / protocol summary

Plus the contract: docs/submission-contract-v<N>.mdx — referenced from agents.mdx.

Plus the script: tools/scripts/validate-cross-refs.ts — deterministic graph and frontmatter validator (per G.10). meta-validate-skill-graph is not a skill; the validator is the script alone, invoked from three points (consumer pre-flight, Worker hard-gate, PR-CI on main).

Skills now carry a parallel requires_paths: block alongside requires:. Where requires: composes other skills into the DAG, requires_paths: declares the documents, deeplinks, calculators, and commune handoffs a procedure needs the customer to obtain. Each entry resolves to a path id catalogued in the Path Directory; the Path Directory is the single source of truth for where each target lives and how to reach it across multiple sources. See §6.12 (see schemas.md) for the path-entry schema and §24.9 (see architecture.md) for the traversal algorithm the harness applies.

Meta-skills are maintainer-seeded canonical content. Skills with category: meta are not submitted via the consumer-AI submission flow and do not traverse the alpha → beta → stable consensus cycle. They are committed directly to canonical.md with status: stable from day one. Updates to meta-skills happen via direct PR review by the maintainer — not via amendment submission — consistent with the constitutional-court framing of the maintainer's role (per §7 (see protocol.md), §17 (see architecture.md) settled decisions). This keeps the protocol meta-layer (drafting walkthrough, decomposition utility) under tight maintainer control while leaving the corpus open to consensus-driven growth.

15.1 Drafting steps (draft flow — target_type=skill | path)

The operational walkthrough is in docs/skill-universe/walking-procedure.md; this subsection summarises the structure.

Tooling. Operator-driven walks are operationalised by bc-corpus-creator, an internal build tool. See build-tools.md for the build-tool specification (including research-report.md and evals.json artefact schemas) and bc-skills/bc-corpus-creator/references/ for the canonical authoring references (research-report shape, evals shape, voice and style, canonical shape, rubric, schema descriptors). Manual walks per the textual procedure in this section remain valid and supported.

  1. Define scope. Start state, end state, success criteria — one sentence each.

  2. Identify category. category from open enum with deterministic guards. (There is no kind field in round 6.)

  3. Authoritative-source research (Belgian-jurisdiction processes only). The drafting agent searches across the source classes in §15.2: legal text where it exists, official admin pages where the procedure lives in practice, professional-body guidance where it applies. Stopping criterion: at least one authoritative citation per major claim.

  4. Procedural research. For commune-level execution detail, the relevant commune website. For edge cases, vetted forums (see §15.2). Aggregate patterns; do not quote individual posts. Stopping criterion: ≥3 independent reports of the same edge case before including.

  5. Origin-country research (origin processes only). Allowlist of official government sources for that country.

  6. Process decomposition (via meta-decompose-process). Identify branching points (region, origin, user category, civil status). Identify reusable sub-processes. Each sub-process triggers a recursive drafting pass — but stop at depth 3 unless rationale.

    Standard branching axes to check explicitly for any Belgian-jurisdiction skill:

    • Region: Brussels-Capital, Wallonia, Flanders divergence — Inburgering / Parcours d'intégration / BAPA
    • EU citizen vs. third-country national: EU 2016/1191 vs. apostille vs. legalisation
    • Civil status: married-to-Belgian fast-track via art. 12bis §1, 3° (5y residence + 3y cohabitation with Belgian spouse); single; divorced; widow(er); cohabiting
    • Origin country: drives apostille (Hague), legalisation (non-Hague), EU 2016/1191 (EU)
    • Capability tier: does the skill require pdf_generation, file_read, etc.?

  7. Volatile values and references. Anything numeric that varies (fees, durations, lead times, age thresholds, document validity periods) goes into a <VV> tag in body MDX with name filled and uid empty (PR-CI fills the uid; §6.11 (see schemas.md)). Citations go into <Ref> tags following the same name-filled / uid-empty pattern. The drafter never invents a uid.

  8. Required documents. Per item: where it comes from, validity period, certification requirements; cited via <span class="dsl dsl-ref">label</span>.

  9. Author the body (MDX, with <VV>, <Ref>, <Observations>, <Path>, <Skill>, and <Risk> tags as appropriate per §6.10 (see schemas.md)). Each requires_paths: entry SHOULD be anchored by at least one inline <span class="dsl dsl-path"><a href="https://becivic.be/paths/…" target="_blank" rel="noopener">Path: …</a></span> in the body, and each requires: entry SHOULD be anchored by at least one inline <span class="dsl dsl-skill"><a href="https://becivic.be/skills/…/canonical" target="_blank" rel="noopener">Skill: …</a></span> — both SHOULD (not MUST): pre-filing or purely informational compositions may legitimately have no single anchor sentence. The cross-ref validator emits an inline_orphan warning when a body tag's id has no matching frontmatter entry but does not fail.

  10. Pre-flight validation. Run tools/scripts/validate-cross-refs.ts via tool_execution (or apply the rules checklist via LLM judgment if tool_execution not available). Resolve any reported issues before submitting.

  11. Self-review checklist. All claims cited; no maintainer-specific content; no PII in examples; capability declarations conservative; citation URLs verified; tags author-empty on uid (no agent-minted uids); banner inferred from status: alpha.

  12. Submit draft (target_type=skill). The Worker stages for 24 h, then opens a PR creating skills/<proposed_id>/canonical.md at status: alpha. PR-CI runs validators and orchestrates uid assignment for any new tags. The maintainer reviews and merges (draft is the one feedback type that requires maintainer review; S31). Once merged, validations from subsequent consumer AIs advance the skill through the state machine. Agent-facing label discipline: prefer "proposal" / "new-artefact proposal" in customer-facing copy to avoid confusion with status: draft on the resulting on-disk artefact (the artefact starts at status: alpha).

15.2 Source classes

Sources are classified by the role they play in drafting, not by a strict allow/deny list. Citation quality is gated; research breadth is not.

Round 6 reframes citation as authoritative sources broadly defined (S46): legal text where it exists, official admin pages and guidance where the procedure lives in practice, professional-body published guidance where it applies. The earlier "primary statutory text only" framing (round-5) was overly restrictive — much of Belgian admin procedure does not come from law but from administrative practice, and citing the law is not always relevant.

Citation-grade (primary) — appropriate for any cited claim in skill body. References cited via <span class="dsl dsl-ref">label</span> MUST resolve to a primary source unless the catalogue entry is explicitly marked grade: secondary with rationale.

  • Statutory (Belgian): Moniteur belge, ejustice.just.fgov.be, *.fgov.be, *.belgium.be
  • Procedural (Belgian admin): SPF / INAMI / ONEM / commune / regional pages — *.brussels, <commune>.be, regional government sites
  • Professional-body guidance (Belgian): published guidance from notaire / avocat / médecin / etc. orders where the order is the authoritative voice on the procedure
  • Origin-country government

Context-grade (secondary) — drafting agent reads for context and edge-case identification. May appear as a <Ref> only if the catalogue row carries grade: secondary and only when no primary alternative exists.

Signal-only (tertiary) — any reasonable web source. Drafting agent reads freely to identify patterns. Not cited under any circumstances.

The classification list is itself versioned at schemas/source-classes.json and proposable via PR. The usage enum that bc-corpus-creator's research-report carries on each source row (orthogonal to citation grade) is documented in build-tools.md, not in this product spec.

15.3 Inclusion rule for edge cases

An edge case identified from any source class can be included if:

  • It has been confirmed by ≥3 independent reports across signal/secondary sources, OR
  • It can be cross-referenced against a primary source

15.4 Search query templates

Embedded in meta-draft-l1-skill so drafting agents have ready-made queries.

15.5 Stopping criteria

  • Statutory: stop after ≥1 citation per major claim, or after exhausting first-page results on 3 well-formed queries
  • Procedural: stop after the commune's own page is fetched, or after 2 commune sites confirm the same procedure
  • Edge cases: stop after 3 independent reports
  • Origin: stop after the official government source is identified

If a stopping criterion is hit but the section still feels thin, mark confidence: low and submit anyway — validations from real users will reinforce or correct it.

15.6 Amendment UX (the amendment flow — lighter than draft)

A consumer AI walking the user through proposing a change to existing content follows a path that depends on what's being changed (post-2026-05-15 taxonomy normalization — amendment is unified across skill / volatile_value / reference / path / path_source via target_type):

  • Volatile-value or reference correction ⇒ amendment with target_type=volatile_value or target_type=reference per §6.2.2 (see schemas.md). Fast-path: D1 INSERT-with-supersede directly (no PR pipeline); lighter capability tier (multi_turn, structured_output only — no web_fetch / tool_execution needed for a scalar correction). The state machine reads the threshold table and promotes the new row on N validations.
  • Skill body or frontmatter edit ⇒ amendment with target_type=skill per §6.2.2 (see schemas.md); structure below.
  • Path field or source edit ⇒ amendment with target_type=path | path_source per §6.2.2; same shape as the skill flow but the diff lands on bc-docs/paths/index.json rather than a canonical body. Path / path_source amendments auto-merge on green PR-CI (same as skill amendments).
  • Free-text caveat, nuance, or anecdote ⇒ concern (renamed from observation) per §6.2.1 (see schemas.md); the prose is attached to target_type=skill / path / path_source and surfaced via the <Observations> aggregator (§6.10).
  • Anything about Be Civic that isn't about an artefact (bug, suggestion, accessibility report, confusion) ⇒ feedback per §6.2.5 (free-text channel; operator-private triage; no public surface).

For an amendment with target_type=skill:

  1. Confirm the skill and the change target. Choose one content.amendment_subtype — body or frontmatter — per §6.2.2 (see schemas.md). "The Required Documents section is missing the proof-of-residence attestation. Want me to draft that addition?" (body) — or — "The skill's applies_to.civil_status doesn't include cohabiting; want me to add it?" (frontmatter). If the user wants to touch more than one subtype, the agent files multiple amendments — one per subtype.
  2. Compose the typed change payload. For body: synthesise the post-edit body, compute the unified diff against the current canonical (diff -u), include as content.body_diff, and pin content.skill_commit to the current canonical's git SHA. For frontmatter: identify the content.frontmatter_change.field_path (dot notation per the skill schema) and the typed proposed_value.
  3. Gather citations as new tags. If the change adds a new claim, the agent introduces <span class="dsl dsl-ref">label</span> tags with uid empty; PR-CI will fill the uids on merge. Do not invent uids.
  4. Compose rationale. Single paragraph, ≤500 chars, naming the skill, the change target, what's changing, and the evidence.
  5. Pre-flight validation. Run tools/scripts/validate-cross-refs.ts against the synthesised post-amendment skill state. For body amendments the script re-applies the diff and verifies it lands cleanly (the same check the Worker runs); for frontmatter it validates the field path and value type. Capture the result in pre_flight_validation_result.
  6. Submit amendment. The Worker stages for 24 h (server-stamps cohort_anchor between cross-ref and timing-step), then opens a PR applying the change to canonical.md. PR-CI runs and auto-merges on green (S31). The merged content lands at the skill's current status (typically alpha if the cohort has reset, stable if it was a same-version maintenance edit).

The amendment path is explicitly lower-friction than draft — most corpus growth happens here. draft is for genuinely-new skill or path territory and is the one path that requires maintainer review.

15.7 Harness consumer obligations

A skill that acts as a harness, orchestrating procedure skills, managing the session lifecycle, and owning submission, carries the protocol obligations in this subsection. These are conformance requirements, not implementation prescriptions. The implementation of each obligation is at the harness author's discretion within the stated constraints.

The harness MUST:

  1. Implement the feedback-template session lifecycle. The four-phase protocol at /agents/feedback-template is the canonical contract:

    • Phase 1: session start with scrub-rules fetch, session-id generation, <USER_DATA_DIR> resolution, orphan scan.
    • Phase 2: during-session buffer append with L1 scrub on every write.
    • Phase 3: session-close presentation with per-item customer approval.
    • Phase 4: validate-then-stage submission. The harness MUST implement all four phases. Deviation from the phase order is a protocol violation.

  2. Resolve <USER_DATA_DIR> per §8.7.3 (see privacy.md). State paths MUST NOT be hardcoded to any specific machine, user home directory, or installation path. The resolution chain is platform-aware: macOS uses ~/Library/Application Support/be-civic/; Windows uses %LOCALAPPDATA%\be-civic\; Linux/XDG uses $XDG_DATA_HOME/be-civic/ or ~/.local/share/be-civic/; final fallback is ~/.be-civic/. The harness logs the resolved path to <USER_DATA_DIR>/.location so subsequent sessions reuse the same directory. Claude Desktop's Cowork tab is available on macOS and Windows as of round-7; both platforms MUST be supported. On a filesystem-less runtime, the harness operates in advice-only mode and announces this in plain language at session start.

  3. Fetch scrub rules on session start. The harness MUST fetch becivic.be/scrub-rules.json at session start and cache the result for the session. If the fetch fails after two retries, the harness MUST NOT submit any observations during the session.

  4. Run L1 scrub on every buffer write. Before appending any item to the observation buffer, the harness MUST apply agent-side L1 scrub: regex pass using the cached scrub rules plus LLM judgment over free-text fields for PERSON names, addresses, dates of birth, and business names tied to individuals. An item that fails L1 scrub MUST NOT enter the buffer in its original form; the harness either generalises the offending field or drops the item.

  5. Deliver first-session disclosure. On first_contact per §24.5 (see architecture.md), the harness MUST present the submission contract framing per §3 (see architecture.md) principle 10 before proceeding to procedural guidance. The framing includes: what Be Civic is, what observations are, that no identity information is collected, that document content is not retained, and that the customer can cancel any submission within 24 hours.

  6. Distinguish observations from analytics. The harness MUST present observations and analytics as separate categories with separate opt-in mechanics, per the C1b amendment §6.2 (see schemas.md). Analytics submission is opt-in; observation submission is the core protocol contract and is not opt-in for a participating session. A customer who declines analytics still receives full procedural guidance and contributes observations through the standard buffer-and-approve flow.

  7. Detect capability tier and guide upgrades. The harness MUST detect the current tier per §24.4 (see architecture.md) and operate within that tier's constraints. It SHOULD offer one-sentence upgrade guidance where a higher tier is available, at most once per session, without blocking the customer.

  8. Not submit without customer review. The harness MUST NOT submit any item to any Be Civic endpoint without presenting that item to the customer and obtaining approval per Phase 3 of the feedback-template. Silent submission is a protocol violation regardless of tier.

  9. Not retain document content. When the customer provides a document (a scan, a photo, a paste of document text), the harness MUST extract only the routing fields relevant to the current procedure and MUST NOT retain the document content in any buffer, profile, or memory file. The extraction result (for example, permit_type: C, validity_end: 2028-06) is stored as routing fields under §8.7 (see privacy.md); the document content is not stored at all.

  10. Own the conversation flow. The harness MUST drive the conversation. The customer answers questions; the customer should not need to know which questions to ask. The harness elicits routing fields, surfaces decisions, and frames next-steps proactively. This is the operating equivalent of §3 principle 10 disclosure: the customer is informed of the contract and then served by it, not left to negotiate it.

  11. Use structured option prompts for routing-field elicitation where the field is enum-or-categorical. For every profile.json field whose type is enum, categorical, or boolean (the majority of the 16-axis catalogue in §8.7.4 (see privacy.md)), the harness MUST present the choice as a structured option prompt (the customer picks from a small set), not as free-text input. Free-text elicitation is reserved for narrative-only fields (in memory/customer_context.md and related files) where the customer's own words are the value. Structured prompts reduce ambiguity, reduce the L1 scrub load, and make the routing fields auditable from the conversation transcript.

  12. Submit feedback per a deterministic decision rule. When the harness detects a content issue or a corpus gap, the choice between feedback types is deterministic, not customer-elected. The harness names the type explicitly to the customer (per the agent-facing label discipline: prefer "proposal" / "new-artefact proposal" over "draft" when there's risk of confusion with status: draft on the resulting on-disk artefact):

    • The harness submits an amendment (with target_type matching the affected artefact) when it has high confidence in a specific change. For target_type=skill, body-subtype carries a unified diff (replace text X with text Y); frontmatter-subtype carries a typed field path + value. For target_type=volatile_value / reference / path / path_source, the typed content shapes apply (per §6.2.2 (see schemas.md)).
    • The harness submits a concern (with target_type matching the affected artefact) when it can flag the gap or accuracy issue but does NOT have replacement text it would defend. Cells:
      • target_type=skill for general accuracy issues with a skill body.
      • target_type=volatile_value for a detected VV discrepancy (deterministic-fire path; the harness fires this when it detects a discrepancy between a cited <VV> value and session evidence, with no LLM judgment).
      • target_type=reference for a citation that has rotted, 404s, or has been superseded.
      • target_type=path for an anecdotal / scoped path report (with scope + specifier for commune-specific or regional-specific cases).
      • target_type=path_source for a concern about a specific source on a specific path.
    • For procedure absence (no skill exists for the procedure the customer is asking about), the harness submits a concern with target_type=skill_graph by default (the corpus-graph-itself-has-a-gap signal). This MUST happen after the gate-skill classifier has classified the opener as procedure-intent (per the gate-classifier obligation on every harness — see architecture.md §24.6 universal flow and the harness's onboarding-orchestration spec) and after the user has accepted the confirmation gate — meta-question and exploring shapes never produce a skill_graph concern. The harness MAY produce a draft with target_type=skill instead if the procedure has been worked through end-to-end during the session (see the no-skill-fallback procedure in §24 (see architecture.md)).
    • For new-source-add on an existing path (a broadly-applicable structural change, e.g. a new offline source the harness has verified), the harness submits an amendment with target_type=path_source and content.amendment_subtype=source_add.
    • For anything not about an artefact (bug report, suggestion, accessibility report, confusion about Be Civic itself), the harness submits a feedback (no target_type; operator-private triage queue; not surfaced on any artefact).
    • For rating (opt-in satisfaction signal per §6.2.7), the harness submits a rating only when the customer has consented to the rating channel and the harness has an explicit star value from the customer. The customer is informed of which feedback type the harness has chosen, and the per-item review gate in obligation 8 still applies.

  13. Reference pricing with an "as of " qualifier. When the harness mentions Cowork pricing, third-party-tool pricing, or any other figure that can drift over time, it MUST attach an "as of " qualifier sourced from its own training knowledge cutoff. This lets future agents detect when their own knowledge is out of date and prompts the customer to verify current pricing before acting on a figure. The harness MUST NOT present pricing as a current fact; it MUST present pricing as a training-time fact with a verification reminder.

  14. Attribute observations to the correct procedure when multiple are active. When profile.json active_procedures contains more than one procedure id, every submitted observation MUST carry the skill_id of the procedure the observation pertains to, NOT the procedure currently in focus. The harness MUST track per-observation attribution as the customer's conversation moves across procedures and MUST NOT batch-attribute by session focus. Example: the customer pivots from nationality-application to address-change five minutes ago, then says "actually I also noticed the language certificate list in your nationality skill is incomplete" — that observation carries skill_id: nationality-application, not the currently-focused address-change.

  15. Route to the no-skill-fallback meta-skill on zero-match. When mcp__becivic__get_graph (or the HTTP parity endpoint) returns zero nodes matching the customer's request after applying filters, the harness MUST route to meta-no-skill-fallback per §24.8 (see architecture.md). The harness MUST NOT silently fall back to general-knowledge mode without invoking the meta-skill; the meta-skill exists to ensure the customer is told openly that the procedure is not in the verified corpus.

  16. Gloss jargon in harness outputs. The harness's own customer-facing outputs (opening framing, decision questions, summaries, recap text) MUST follow §15.8 invariants 7 (inline-bracket or footer glosses for admin/legal jargon on first use) and 8 (legislation references in prose form, not parenthetical citations). If the harness's output draws on a procedure skill body that already glosses a term, the harness MAY skip re-glossing it in the same conversation; the gloss-tracking state is session-scoped.

  17. Traverse the Path Directory deterministically. When a procedure skill declares requires_paths, or the customer requests a document or tool covered by the Path Directory, the harness MUST traverse paths per the agent-traversal algorithm in §24.9 (see architecture.md). The traversal MUST honor source priority order, eligibility predicates against the customer's profile, the fallback_only flag (with offline sources always last), and explicit user consent before invoking sources flagged audited_document_delivery: true. The harness MUST submit a validation per attempt: confirm on success, reject with rationale on failure.

  18. Present handoffs in plain English. When a source's actor.handoff.when != none, the harness MUST present the agent_responsibility, user_responsibility, and resumption text to the customer in plain English before handing off. The handoff text MUST follow §15.8 invariants 7 (gloss admin and legal jargon on first use) and 8 (legislation references in prose form). The harness MUST NOT hand off silently. The customer always knows what they are being asked to do, what they will see, and how to signal "done."

  19. Apply focused attention to <Risk>-wrapped content. When the harness enters skill-body content wrapped in a <Risk> inline tag (per §6.10 (see schemas.md)), it MUST slow down and name the stakes to the customer in plain language — using the tag's reason attribute if present, otherwise summarising from the wrapped prose. Focused attention applies until the closing tag. The tag's presence IS the signal; there is no severity level to read. The eligibility-assessment step shape (introduced in round-7.2 for irreversible routing calls at [Process] step 1) fires when that step body is wrapped in <Risk>, NOT when frontmatter declares a skill-level risk classification. The harness MUST NOT read a routing_risk frontmatter field; that field is retired as of round-7.3. When a <Risk>-wrapped step invokes a sub-skill via <span class="dsl dsl-skill"><a href="https://becivic.be/skills/.../canonical" target="_blank" rel="noopener">Skill: ...</a></span>, focused attention carries into the sub-skill walk and resumes normal attention on return; sub-skills may carry their own internal <Risk> tags independently.

The harness SHOULD:

  1. Provide orphan-session recovery. On session start, the harness SHOULD scan for orphan buffer files and surface them to the customer per the feedback-template orphan-scan protocol. Orphan sessions older than 72 hours SHOULD trigger a deterministic session_outcome: abandoned_inferred submission. This path is code-only; no LLM judgment.

  2. Pre-populate routing from profile.json. When a profile exists, the harness SHOULD read the routing fields it needs before asking the customer. It SHOULD ask only for fields that are not already in the profile and are required by the current procedure skill's profile_requirements list.

  3. Recover gracefully from customer deletion of <USER_DATA_DIR>. If the customer deletes the customer-side state directory and returns in the same project context, the harness MAY use project-scoped context (prior conversation transcripts visible in the project, vendor key-value stores [e.g., Project Memory in Anthropic platforms] if accessible) to avoid restarting routing-field elicitation from zero. It MUST NOT silently re-create the deleted profile.json or memory/ files. Re-creation requires explicit customer re-consent: the harness presents what it remembers and asks the customer to confirm before writing.

The harness MAY:

  1. Surface upgrade options proactively. Where the harness detects that a higher tier would provide a materially better experience (for example, the customer is at T2 and mcp.becivic.be is not connected), the harness MAY note this once without repeating it.

15.8 Skill body discipline

Customer-facing skill bodies (both the harness SKILL.md and procedure-skill SKILL.md or canonical.md) carry regulation in customer voice. They are the text a customer's AI agent reads as operating instructions. They are not internal design documents. The invariants in this subsection apply to all customer-facing skill bodies.

  1. No implementation paths. Skill bodies MUST NOT contain absolute filesystem paths, relative filesystem paths tied to a specific install, machine-specific paths, or installation-specific paths. State paths are resolved at runtime per §8.7.3 (see privacy.md) and §15.7 obligation 2; they are not specified in skill text.

  2. No operator-internal references. Skill bodies MUST NOT contain references to bc-operations, sprint codes (W-prefixed sprint identifiers), design document paths, internal conversation transcripts, or any URL that resolves only within the operator's local filesystem. Customers' agents do not have access to bc-operations and should not be directed there.

  3. No design rationale. Skill bodies carry what the agent should do, not why the protocol was designed as it is. Design rationale lives in bc-operations design documents and in this spec's settled-decisions sections (§17 (see architecture.md)). If a skill body explains a design decision, that text is removed.

  4. No dogfooding notes. Skill bodies MUST NOT contain operator-facing iteration notes, "dogfooding discipline" sections, patch-rate metrics, graduation gates, or any text addressed to the maintainer rather than to a customer's agent.

  5. Customer register. The register is Wikipedia or Citizens Advice: concrete, declarative, citation-grounded, no hedging, no AI vocabulary. This applies equally to harness bodies (operational instructions to the agent) and to procedure bodies (steps and documents for the customer).

  6. Voice rules from §15 apply in full. The skill-drafting voice constraints (no hedging, no maintainer-specific examples, conservative capability declarations) apply to harness bodies as well as to procedure bodies.

  7. Customer-readable jargon. Customer-facing skill bodies MUST gloss admin and legal jargon on first use. The gloss is either inline in brackets immediately after the term (preferred for short, single-word terms) or in a "Terms used in this message" footer at the end of long-form prose (preferred when more than two terms appear in one paragraph). Example: "You will need a legalisation of your foreign birth certificate (the process of getting a document recognised for use by Belgian authorities)." Skill authors maintain the glossary inline; the harness does not transform skill text at runtime.

  8. Legislation references in prose, not parenthetical citations. Customer-facing skill bodies MUST present legislation references in prose form ("Section 12 of the Code of Belgian Nationality requires X"), not as parenthetical decorations the customer has to decode ("X is required (art. 12bis CN; Mb. 1984-06-28)"). The authoritative source (article number, Moniteur publication date, Belgilex link) goes in a sources: frontmatter list or a bottom-of-body ## Sources section, where the agent can cite it when challenged, but the body prose names the law conversationally. Customers should know the guidance comes from law without needing legal-citation literacy.

  9. Reference paths by ID, not by URL. When a skill body needs to mention a path (for example, "the customer will fetch their residence certificate"), it MUST reference the path by its id (e.g., certificat-residence-historique), not by a hard-coded URL. The Path Directory (§6.12 (see schemas.md)) is the single source of truth for URLs and acquisition routes; embedding URLs in skill bodies creates rot when sources move, deprecate, or split across regions. The harness resolves the path id to a concrete source at traversal time per §24.9 (see architecture.md).

  10. Inline tag resolution. Every inline <span class="dsl dsl-path"><a href="https://becivic.be/paths/…" target="_blank" rel="noopener">Path: …</a></span> and <span class="dsl dsl-skill"><a href="https://becivic.be/skills/…/canonical" target="_blank" rel="noopener">Skill: …</a></span> tag in a skill body MUST resolve to an existing catalogue entry — paths.<id> in bc-docs/paths/index.json for <Path>, and bc-docs/skills/<id>/canonical.md for <Skill>. PR-CI (validate-cross-refs.ts) fails on unresolved inline path or skill tags. This mirrors the §6.10 (see schemas.md) <Ref> and <VV> resolution discipline. Orphan warnings (body tag without matching requires: / requires_paths: frontmatter entry) are advisory, not failing — the informational-mention pattern is supported.

  11. Positioning copy follows architecture.md §3 principle 14. Customer-facing skill bodies MUST frame Be Civic as a tool the user's agent uses, not as an agent itself. Acceptable: "Your agent will walk you through the apostille using Be Civic's procedure." Not acceptable: "Be Civic will help you with your apostille." This applies to harness bodies (operating instructions to the agent) and to procedure bodies (steps and documents for the customer). The harness's customer-facing prose (opening framing, confirmation gate copy, post-submit acknowledgement, summary text) MUST follow the same rule. D9.

Scope. Procedure skill bodies (canonical.md for corpus skills) are additionally governed by §15.1. The harness SKILL.md is additionally governed by §15.7. Neither body type is exclusively governed by one section; both apply to both, with the §15.7 obligations specifically distinguishing the harness.

Backlog. W20 procedure skill drafts require cleanup against these invariants. The cleanup is an implementation backlog item tracked under §14 (see README.md) Phase 4; it is not a blocker for landing this section.

15.9 OSS-alignment frontmatter

Be Civic publishes its skill package as open source from v1 (per the §17 (see architecture.md) settled decision recorded in design-decisions Cluster 4). The following SKILL.md metadata frontmatter fields are committed for v1 and SHOULD be present on every harness and procedure skill published as part of Be Civic:

metadata:
  privacy-contact: "privacy@becivic.be"
  data-retention: "customer-side only; see https://becivic.be/privacy"
  opt-in-required:
    - analytics

Field semantics:

  • privacy-contact: the contact address for customer privacy questions. SHOULD be set on the harness skill. MAY be omitted from procedure skills (they inherit from the harness).
  • data-retention: a human-readable summary of data retention, or a URL. The v1 value for all Be Civic skills is "customer-side only" because no Be Civic server stores per-customer state (§3 (see architecture.md) principle 11). Updates to this field MUST remain accurate; a change in the retention policy is a protocol amendment under §17 (see architecture.md).
  • opt-in-required: a list of submission types that require explicit customer opt-in before submission. In v1 the only value is analytics. observations is not in this list: observations are the core protocol contract per §3 (see architecture.md) principle 10 and are buffered, approved, and submitted under the feedback-template flow rather than under an opt-in toggle.

Install-time symlink. The setup script for the harness SHOULD create a symlink at ~/.agents/skills/becivic/ pointing to ~/.claude/skills/becivic/. This enables agentskills.io cross-client discoverability without duplicating skill files. The customer MAY remove the symlink at any time without affecting Claude-native operation. The setup script MUST NOT fail if the symlink already exists or if ~/.agents/skills/ does not exist.

OSS positioning. The harness and procedure skills are published under CC-BY-4.0 in line with the rest of the corpus (§3 (see architecture.md) principle 6b). The OSS positioning trigger conditions for any future relicensing or scope change are deferred per §18 (see architecture.md).

Path-catalogue alignment. Path-catalogue entries (§6.12 (see schemas.md)) follow the same OSS-alignment fields as skills. The Path Directory carries privacy-contact, data-retention, and opt-in-required semantics at the catalogue level rather than the per-entry level, because the harness reads the catalogue as a single artefact at session start. Per-path-source actor blocks (per the D24 settled decision in §17 (see architecture.md)) carry the safe-by-default behaviour for credential handling and document delivery; the catalogue file itself inherits the harness's privacy contact and retention values.

Cross-references

Cross-doc references are inlined throughout this document in the form §X.Y (see .md). The list below was the pre-reconciliation manifest from the 2026-05-11 split, retained for audit; it can be deleted at the next split-or-merge cycle.

  • §3 (Non-negotiable principles, including principle 10 opt-out) — see architecture.md §3
  • §6.1 (Skill schema / status enum / alpha banner / composition rules) — see schemas.md §6.1
  • §6.2.1 (Observation submission schema) — see schemas.md §6.2.1
  • §6.2.2 (Skill amendment schema) — see schemas.md §6.2.2
  • §6.11 (Catalogue UID convention / uid-empty authoring) — see schemas.md §6.11
  • §7 (Trust model / maintainer review queue / Tier B protocol amendments) — see protocol.md §7
  • §8.7.3 (<USER_DATA_DIR> resolution) — in privacy.md
  • §8.7 (Consumer-side state contract / profile.json) — see privacy.md §8.7
  • §9 (State-machine promotion / draft flow) — see lifecycle.md §9
  • §17 (Settled decisions / CC-BY-4.0 licence / meta-skills) — see architecture.md §17
  • §18 (Open questions / OSS trigger) — see architecture.md §18
  • §24.4 (Capability tiers) — see architecture.md §24.4
  • §24.5 (Three-tier returning-user adaptation / first_contact) — see architecture.md §24.5