Machine-Writable Entry Points

Marker Block Specification

Machine-writable files use marker blocks to delineate tool-managed regions.

Core rules:

1. •Each file must have exactly one pair of BEGIN/END markers.
2. •The literal marker strings must appear only as standalone marker lines.
3. •Content between markers is tool-owned: no manual edits.
4. •Content outside markers is human-owned and preserved.
5. •Tools replace the entire block atomically.

ABILITY.md Marker Block

```markdown
<!-- BEGIN ABILITY_INDEX -->
```yaml
high_level_abilities:
  - id: <ability_id>
    name: <human_readable_name>
    type: workflow | agent
    summary: >
      One-line description of the ability.
    registry_path: /.system/registry/high-level/<ability_id>.yaml

low_level_abilities:
  - operation_key: <operation_key>
    kind: script | api | mcp
    summary: >
      One-line description of the operation.
    registry_path: /.system/registry/low-level/<operation_key>.yaml
```
<!-- END ABILITY_INDEX -->
```

Inclusion and ordering:

• •Entries are generated from registries under /.system/registry/high-level/ and /.system/registry/low-level/.
• •Inclusion is controlled by entrypoints on registry entries (repo-root absolute ABILITY catalog root paths); an entry appears in <entrypoint>/ABILITY.md iff <entrypoint> is listed in entrypoints.
• •Ordering: stable sort high-level by id, low-level by operation_key.

Tool Ownership Contract

CI Validation

CI pipelines should validate:

1. •Structural integrity: exactly one BEGIN/END pair per file.
2. •YAML validity: content between markers is valid YAML.
3. •Reference integrity: all registry_path values point to existing files.
4. •Path format: all paths are repo-root absolute (begin with /).

Related documents