Add a resource type

Read src/poly/resources/AGENTS.md first; this skill expands its checklist.

1. Study an existing resource

• src/poly/resources/entities.py: a simple YamlResource.
• src/poly/resources/resource.py: the base classes, register_resource and load_resources_from_projection.
• src/poly/resources/__init__.py: where classes are imported.
• AgentStudioProject.find_new_kept_deleted and _make_resource_mapping in src/poly/project.py: how resource types are handled generically.
• For a resource that belongs to a parent (a step in a flow, an overwrite in a variant): FlowStep in flows.py. It stores the parent id and name as fields and resolves them from the enclosing folder name in read_local_resource.

2. Write the class

Create src/poly/resources/<name>.py:

• Subclass YamlResource (or Resource / MultiResourceYamlResource) and implement the abstract methods:
  • command_type
  • build_create_proto, build_update_proto, build_delete_proto
  • file_path, raw, validate
  • to_yaml_dict, from_yaml_dict
  • from_projection, read_local_resource, discover_resources
• Add make_pretty / from_pretty if names or IDs need substituting, and get_resource_prefix() if other resources can reference this one.
• Decorate it with @register_resource("<name>"). That fills RESOURCE_NAME_TO_CLASS, RESOURCE_CLASS_TO_NAME and PROJECTION_REGISTRY. There is no other registration step.
• from_projection is a classmethod that parses its own keys out of the raw projection dict.
• validate should reject everything the platform would reject.

3. Wire it in

• Import the class in src/poly/resources/__init__.py, which makes the decorator run.
• If the file name is a cleaned version of the real name (accents, casing or punctuation stripped, like Topic and ChildTopic), add the class to the name-recovery condition in find_new_kept_deleted in src/poly/project.py, and import it there.

4. Test it

In src/poly/tests/resources_test.py (see the write-tests skill), cover:

• the YAML round-trip
• validate (valid and invalid)
• file_path
• from_projection

For a parent-scoped resource, also test that read_local_resource resolves the parent from the folder name and copes with an empty resource_mappings list.

Add an example of the resource to src/poly/tests/test_projects/test_project/.

5. Document it

• src/poly/docs/<name>.md: the YAML shape, served by poly docs.
• docs/docs/reference/resources/: follow the AGENTS.md in that directory, and add the page to docs/mkdocs.yml.
• If a user skill in skills/ describes the area, update it.

6. Check

uv run ruff check . --fix, uv run ruff format ., then the ci-check skill. Never touch src/poly/handlers/protobuf/ or src/poly/types/; if the protobufs lack the resource, stop and say so.