edercnj/x-internal-extract-asset-metadata

Output Policy

• Output: JSON only — no prose, no markdown wrapping, no explanations.
• Efficiency: Read only the file header (first 80 lines max); stop after --- closes the frontmatter block.

🔒 INTERNAL SKILL Invoked only by orchestrator skills (x-internal-select-context-packs, x-plan-architecture, x-review-*).

Skill: x-internal-extract-asset-metadata

Purpose

Parse the YAML frontmatter block of a patterns or knowledge file and return a normalized JSON envelope for downstream dynamic context loading.

This skill is the single parsing point for all frontmatter metadata — it abstracts YAML parsing so consumers never need to handle raw frontmatter directly.

Triggers

Used only through inline invocation:

Skill(skill: "x-internal-extract-asset-metadata",
      args: "--asset-path src/patterns/backend/software-architecture/hexagonal/patterns.md")

Parameters

| Parameter | Required | Description | |---|---|---| | --asset-path | Yes | Relative path to the .md file from repo root | | --field | No | If provided, return only the specified top-level field value instead of the full envelope |

Algorithm

1. Read the file at <asset-path>.
   - Read up to the first 100 lines only (frontmatter is always at the top).
   - STOP reading after the second `---` line (closing delimiter of YAML frontmatter).

2. Extract the YAML block between the first and second `---` markers.
   - If no frontmatter found → return ERROR_NO_FRONTMATTER envelope.

3. Parse YAML fields into the normalized envelope (§ Output Contract).
   - Apply defaults for missing optional fields (see § Defaults).

4. If --field is provided:
   - Return only that field value as a JSON primitive or array.
   - If field not present → return null.

5. Return the JSON envelope (single-line, no pretty-print).

Output Contract

Success — full envelope

{
  "status": "ok",
  "asset_path": "src/patterns/backend/software-architecture/hexagonal/patterns.md",
  "name": "backend-hexagonal-patterns",
  "type": "patterns",
  "description": "ISSP patterns for backend hexagonal architecture (ports and adapters).",
  "capabilities": ["architecture", "hexagonal", "backend"],
  "load_phase": ["plan", "implement", "review"],
  "mandatory_level": "required",
  "domain": "shared",
  "arch_categories": ["B", "C"],
  "arch_questions": [
    {
      "id": "ARCH-HEX-01",
      "category": "B",
      "question": "Qual estilo arquitetural será aplicado neste serviço?",
      "choices": ["hexagonal", "clean-architecture", "onion", "layered"],
      "mandatory": true,
      "inheritable": true,
      "phase": "plan"
    }
  ],
  "scoring": {
    "enabled": true,
    "max_positive_score": 35,
    "max_negative_score": -30,
    "go_nogo_threshold_pct": 80,
    "go_with_reservations_pct": 65
  },
  "triggers_context_packs": [],
  "consumed_by_skills": ["x-plan-architecture", "x-review-specialist", "x-implement-task"],
  "deprecation_status": "active",
  "superseded_by": null
}

Error — no frontmatter

{
  "status": "ERROR_NO_FRONTMATTER",
  "asset_path": "<path>",
  "name": null,
  "type": null,
  "capabilities": [],
  "load_phase": [],
  "arch_questions": [],
  "scoring": null,
  "triggers_context_packs": []
}

Error — file not found

{
  "status": "ERROR_FILE_NOT_FOUND",
  "asset_path": "<path>"
}

Field Defaults (when field is absent or null in frontmatter)

| Field | Default | |---|---| | capabilities | [] | | load_phase | ["plan", "implement", "review"] | | mandatory_level | "recommended" | | domain | "shared" | | arch_categories | [] | | arch_questions | [] | | scoring.enabled | false | | scoring.max_positive_score | 0 | | scoring.max_negative_score | 0 | | scoring.go_nogo_threshold_pct | 80 | | scoring.go_with_reservations_pct | 65 | | triggers_context_packs | [] | | consumed_by_skills | [] | | deprecation_status | "active" | | superseded_by | null |

Error Handling

| Condition | Behaviour | |---|---| | File not found | Return ERROR_FILE_NOT_FOUND envelope; do NOT abort the caller | | No frontmatter block | Return ERROR_NO_FRONTMATTER envelope; do NOT abort the caller | | Malformed YAML field | Use default value; add "parse_warnings": ["field X malformed"] to envelope | | --field not present in frontmatter | Return null for that field |

Governance

• Schema reference: knowledge/shared/governance-baselines/asset-frontmatter-schema/knowledge.md
• Do not cache results across skill invocations.
• This skill has NO side effects — it is purely read-only.