---
name: missing-skill-completeness-detect
description: Engine substrate for the heartbeat-driven detector that finds active user-facing skills loaded into the agent's system prompt but lacking the structural fields (triggers / tools_granted) needed to actually activate or execute. Proposes the fix for user approval.
title: Missing Skill Completeness Detector
category: _meta
status: active
author: agentic
metadata:
  priority: 4
---
## Purpose

Closes the load-bearing gap from the `feedback_main_agent_orchestrator.md`
rule (2026-04-28): the main agent must see every active skill AND be
able to activate + execute it. A skill with `status: active` but no
`triggers:` AND no `tools_granted:` ships as documentation in the
agent's prompt while being structurally inert at runtime.

The canonical regression is `archer-presentation` (2026-04-28): an
`active` skill in the user's vault declared brand-style specs but had
no triggers (so `match_skills("archer futura...")` returned empty) and
no tools_granted (so the agent had brand specs but no procedural path
to execute). The agent produced a generic deck instead of the
intended four-version Archer Futura output, with no signal that the
skill failed to fire.

This detector closes the gap PROACTIVELY at the bookkeeping layer:
walk every active user-facing skill, classify each gap, and propose
the fix for user approval.

## When this fires

Heartbeat-driven, daily by default. Pure deterministic scan — no LLM,
no log analysis, just structural inspection of loaded skills:

* `triggers:` is empty/missing → can't activate via lexical match
* `tools_granted:` is empty/missing → no execution path

For each incomplete skill, the proposal carries:

* the **list of missing fields** (so the user sees what's wrong)
* a **fix steps** rationale (concrete YAML edits to make)
* an **idempotent stable id** keyed on the skill name — re-running
  daily on a vault with no changes is a no-op

## What it doesn't do

* **Never edits the SKILL.md frontmatter.** The right values are
  domain-specific (which user phrases activate this skill, which
  tools does it actually call). A developer or the user supplies them.
  Approval here is acknowledgment + queueing, not automation.
* **Never proposes for engine substrates.** Skills under `_meta/` are
  read by code at known call sites (e.g. `_meta/ontology` is read by
  KnowledgeGraph, `_meta/skill-retrieval` by Orchestrator). They don't
  need user-facing activation triggers or tool grants. The
  `_is_engine_substrate()` filter excludes them by category.
* **Never proposes for inactive skills.** Drafts and archived skills
  shouldn't fire as orphans.
* **Never blocks dispatch.** A structurally-incomplete skill is
  documentation in the prompt; it doesn't break the agent.

## Output format

For each incomplete skill, the detector writes one proposal to:

```
<vault>/agntspace/memory/pending/skill-completeness-proposals/cap-<sha8>.json
```

The proposal carries:

* `kind: "skill-completeness"`
* `target`: the skill name (e.g. `archer-presentation`)
* `title`: "Complete skill: <name>"
* `description`: one-paragraph summary naming the gaps
* `rationale`: longer explanation + concrete fix steps
* `payload`: structured data for the approve handler:
  - `skill_name`, `skill_title`, `category`
  - `missing_triggers`: bool
  - `missing_tools_granted`: bool
  - `gap_count`: int
  - `gap_summary`: human-readable list

## Tuning knobs (`config/detect.yaml`)

* `enabled` (bool, default true) — gate the whole detector
* `require_triggers` (bool, default true) — flag skills with no
  triggers; turn off if the vault relies purely on semantic match
* `require_tools_granted` (bool, default true) — flag skills with no
  tools_granted; rarely turned off (a user-facing skill almost
  always needs at least one tool)
* `excluded_categories` (list, default empty) — extends the engine-
  substrate exemption beyond `_meta`
* `skip_if_pending` (bool, default true) — dedup vs in-flight
  proposals
* `cadence_hours` (int, default 24) — heartbeat interval

Edit YAML, restart server, no code change. (Rule 12.)

## Approval semantics

Approval is acknowledgment + queueing — editing SKILL.md frontmatter
is a manual change because the right field values are domain-
specific. The approve handler records a medium-importance activity
event and removes the pending file. The user (or the healer agent)
opens the SKILL.md and adds the missing fields.

Rejection is silent — removes the pending file, emits a
`user_override` activity event, no further side effects. The skill
stays loaded as-is.

## Why this is a Rule 21 capability and not just a lint check

The proposal is the user-facing artifact. Lint output gets ignored;
a `/proposals` inbox entry is reviewed. Rule 21 says every gap the
agent observes becomes a user-reviewable proposal — this detector is
the enforcement.
