# machine-writable-entrypoints

> Machine-writable entrypoints and marker blocks. Keywords: markers, machine-writable, entrypoints.

- Author: willyu1007
- Repository: willyu1007/AI_First_Template
- Version: 20251224182030
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/willyu1007/AI_First_Template
- Web: https://mule.run/skillshub/@@willyu1007/AI_First_Template~machine-writable-entrypoints:20251224182030

---

---
name: machine-writable-entrypoints
description: "Machine-writable entrypoints and marker blocks. Keywords: markers, machine-writable, entrypoints."
---
# 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
```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

| Aspect | Specification |
|--------|---------------|
| Write method | Full block replacement (atomic) |
| Read method | Parse YAML between markers |
| Validation | Tool validates schema before write |
| Conflict handling | Tool overwrites; manual edits are lost |
| Idempotency | Same input produces identical output |

## 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