Draft a new Be Civic skill end-to-end

Use this skill when the user asks for help with a Belgian administrative process the corpus does not yet cover, and you have the capability tier to file a skill_draft (multi_turn, structured_output, web_fetch, tool_execution, file_read). Walk through the steps below in order. Stop at any step if a stopping criterion fires; mark the gap and continue.

Step 1 — scope the skill

Write three sentences before researching: start state of the user, end state after the process, success criterion that distinguishes "done" from "in progress". If you cannot write the three sentences, the process boundary is wrong — narrow the scope or hand back to the user.

Map the scope to one discrete service on the relevant authority's website. A skill covers one service, one outcome. If the user's task spans two services (e.g., commune registration AND mutuelle enrolment), draft two skills and link them via requires.

Step 2 — resolve kind and category

The kind field has been removed from the schema (resolved per BC-DESIGN-002 Option A; see specification.md §17). Skip kind selection. Move directly to category.

Pick category from data/categories.json:

• belgium-federal — federal services (SPF, INAMI, ONEM)
• belgium-flemish-region, belgium-walloon-region, belgium-brussels-region — regional services
• belgium-commune — commune-level services with per-commune variation handled inside the body
• origin-<cc>[-<area>] — origin-country sub-skills (ISO-3166-1 alpha-2)
• agent-tooling — sub-skills describing agent-side procedures (rendering, dossier assembly, output formatting); free-form body, no canonical sections
• meta — reserved for the drafting and decomposition skills only; do not use for new skills

If no existing category fits, propose a new kebab-case category in the draft. The Worker auto-extends categories.json on first commit, subject to Levenshtein-≤2 typo defence.

Step 3 — plan the context-gathering structure

Decide how the skill establishes context with the user before stepping through the process. Three questions to settle, in this order:

Eligibility. What are the hard prerequisites the user must meet before this skill can run at all? (5 years legal residence; D-visa held; commune registration completed; etc.) Failed eligibility means the agent redirects or refuses; it does not proceed with a partial run.

Intent. What confirms the user is in the right skill? Steering questions that reveal the user wants something this skill does not cover (e.g., naturalisation under art. 19, not declaration under art. 12bis) point the agent at the correct skill instead.

Process state. For skills that absorb existing skills as components (chain-shaped via multiple requires entries), write ## Process so each step's completion is observable from user context (the deliverable produced, the actor engaged, the document held). A consuming agent then maps the user's situation to the right step from the skill body and conversation context.

Eligibility and intent commonly fuse into a single decision tree — the routing logic that selects an eligibility-defined sub-route is the most frequent pattern (12bis's five sub-categories of art. 12bis §1; F-visa's three sponsor types under art. 10 / 40bis / 40ter). When fused, name the body section ## Eligibility & route selection and structure it as a decision table or branched checklist. Split into ## Eligibility and ## Intent check only when the two genuinely don't depend on each other.

The agent does not re-ask context it already has. Write each gate so it is parseable from prior conversation: distinct, named, answerable from a few sentences of user history. The agent will scan its session before asking; redundant questions are a banned behaviour.

For component skills consumed only via composition (loaded by a parent skill via requires rather than directly by the user), eligibility and intent commonly inherit from the parent — capture only what the component itself selects on (e.g., apostille route depends on Hague accession at document issue date; that is the component's intent gate, not a fresh eligibility test on the consuming user).

Step 4 — statutory research

Find the primary law and procedural source. Allowlisted hosts from data/source-classes.json produce primary citations; everything else is secondary or signal-only.

• Federal statutes: ejustice.just.fgov.be (Justel). Capture the numac — the references block uses it as a multilingual shortcut.
• Federal portal: *.fgov.be, *.belgium.be
• INAMI / RIZIV: *.inami.fgov.be, *.riziv.fgov.be
• Foreign affairs: *.diplomatie.belgium.be
• Regional: *.bruxelles.be, *.brussels, *.wallonie.be, *.vlaanderen.be
• EU law: eur-lex.europa.eu, *.europa.eu
• Apostille: hcch.net

Stopping criterion: at least one statutory citation per major claim, or three well-formed queries exhausted. If exhausted with no primary source, drop the claim.

Step 5 — procedural research

Find what the authority's own service page says. For commune-level execution, fetch the relevant commune's website; for federal services, the SPF service page; for regional services, the regional portal. Aggregate patterns; do not quote individual users.

For edge cases drawn from secondary or signal-only sources (forums, NGO write-ups), include only when ≥3 independent reports confirm the same pattern OR one primary cross-reference exists. Stopping criterion: the authority's own page is fetched, or two commune sites confirm the same procedure.

If a commune host is not yet in the primary allowlist, citations to that commune's site are secondary and require a rationale on the references entry.

Authorities cited in the body should be referenced via authority_id in frontmatter, resolving to an entry in data/authorities.json. If the relevant authority is not yet in the catalogue (e.g., a previously unmodelled commune-level body), the drafter adds an entry as part of the draft submission. Volatile values (fees, deadlines, thresholds) shared across skills (DVZ fees, RIS thresholds, indexed values) live in data/volatile-values.json and are referenced via volatile_value_ids: [...] in frontmatter; truly skill-local volatile values stay inline. The catalogue id pattern is descriptive (e.g., dvz-visa-handling-fee-long-stay-d-eur, ris-monthly-eur-2025-couple-no-dependants).

Step 6 — origin-country research

Skip this step unless the Belgian process requires documents from the user's country of origin. When required, identify the origin-country government source for each document.

• Map each required origin document to one origin-country sub-skill (existing or to be drafted): birth certificate, criminal-record check, marriage certificate, etc.
• Allowlist: official government sources for the origin country
• Stopping criterion: official source identified per document; further detail comes from observations

If the origin country has multiple jurisdictions (US states, German Länder), note the granularity and consider whether the sub-skill is per-country or per-jurisdiction.

Step 7 — decompose

Invoke meta-decompose-process. Pass the in-progress scope description and the candidate category. The component skill returns a list of decomposition decisions:

• Units to extract as their own component skills, with proposed id, category, one-line description
• Units to inline in the parent body
• Reuse pointers — requires entries for component skills already in the corpus
• Branching axes that affect this skill (region, EU vs third-country, civil status, origin country, capability tier)

For each "extract" decision the parent skill records a requires entry; each new component triggers a recursive draft pass through this skill. Stop recursion at depth 3 unless rationale.

Chain absorption. When a new skill is naturally a chain (event-triggered, sequencing several existing entry-point-shaped skills), it requires the existing skills as components — no demotion, no new field, no new tag (kind is gone). Each component remains independently entry-point-shaped: a user who enters the corpus at any link of the chain loads only the component they need. The chain main and components share the same requires relation. Drafters of a chain main record the chain framing in the intro paragraph and the route-selection table.

Step 8 — identify volatile values

List every numeric value that drifts: fees, processing times, deadlines, age thresholds, document validity periods. Each becomes a named-scalar entry in volatile_values with the unit baked into the key.

• Right: appointment_lead_time_weeks, apostille_fee_eur, registration_deadline_days
• Wrong: appointment_lead_time (no unit), cost (vague)

Cite each volatile value to the primary source the value came from. When the value drifts, observations against this skill drive a skill_amendment that updates only the named scalar — the body wording stays put.

Step 9 — determine output artefacts

Decide what artefact (if any) this skill produces. Three artefact classes:

• Application dossier — the skill ends with the user filing a dossier at a Belgian authority (commune, consulate, SPF). Add dossier-compilation to requires. The body's ## Bring in original section becomes the dossier-compilation sub-skill's input; dossier-compilation produces the index page, table of contents, and originals callout.
• Working MD only — the skill produces advice, a checklist, or a referral; no PDF deliverable. The agent maintains its working notes (agent discretion; the agent offers to save them locally with the user's permission per /agents).
• None — pure advisory — e.g., advising on how to obtain a Washington birth certificate; the user takes action through external channels.

State which class applies in the skill's intro paragraph. For dossier-class skills, the ## Bring in original section is mandatory.

Skill capability assumption: declare in requires_capabilities what a fully-capable agent has. Do not write graceful-degradation logic into the skill body — that is the consuming agent's responsibility per /agents. The skill body assumes capabilities are present.

Step 10 — document the checklist

List every document the user must bring, with provenance per item:

• Source — origin sub-skill via requires if origin-country, otherwise the issuing Belgian authority
• Validity period — how long the document remains acceptable from issue date
• Certification path — apostille (Hague countries), EU 2016/1191 multilingual form (EU member states), consular legalisation (non-Hague non-EU), sworn translation (FR / NL / DE)
• Form required — original / certified copy / printout acceptable. This drives the ## Bring in original callout in the body.

Match the certification path to the user's origin country via the applies_to.origin_countries filter or via a selects_on clause on the requires entry.

For dossier-class skills (per step 9), every checklist item carries a form-required marker. The dossier-compilation sub-skill reads these markers to generate the originals warning on the index page; without them, the warning cannot be produced.

Step 11 — author the body

Write the body in Skill Body Voice [agents-submit-draft]:

• Imperative for instructions: "File", "Bring", "Schedule"
• Conditional for branches: "If you arrived on a long-stay D visa, ..."
• Citation-anchored: every statutory or procedural fact carries an inline [ref-id] token
• Calm declarative for statutory facts; no hedging, no editorialising
• Compact: prose decoration costs token budget when loaded into agent context
• UK English: organise, behaviour, centre, licence (noun), analyse

The agent consuming this skill assists its user using context provided by Be Civic; it does not represent Be Civic and does not claim legal standing on Be Civic's behalf. The skill body should not instruct the agent to speak as Be Civic.

Body opening — human-CTA Tip block

Every skill body opens with a Tip block addressed to human visitors who land on the page directly (e.g. via search). The page is dual-audience: AI agents fetch the body programmatically and read past it; humans get a prefilled prompt to paste into their assistant. The Tip's URL is the full URL of the skill page itself — the proposal path while version_status is alpha or beta, the canonical path once stable.

Place the Tip immediately after the YAML frontmatter, before any state caveat (<Warning> for alpha, the existing `

<Tip>
**Reading this as a human?** Paste this into your AI:

```text
Load <full URL of this skill page> and walk me through it for my situation.
```

</div>

(intro paragraph — what this skill does; in/out of scope; artefact class per step 9)
## Statutory basis              recommended
## Eligibility & route selection  required (or split into ## Eligibility + ## Intent check
                                  per step 3 when the two are independent)
## Required documents           required
## Bring in original            required for dossier-class skills; omit otherwise
## Process                      required (numbered steps)
## Known surprises              recommended
## Verify with [authority]      required (replace [authority] with the concrete authority)
(closing disclaimer)
## References

(intro paragraph — when invoked, by whom)
## Required documents           required if any
## Bring in original            required if applicable
## Process                      required
## Known surprises              recommended
## Verify with [authority]      required
(closing disclaimer)
## References