new-entry
Scannednpx machina-cli add skill ea-toolkit/architecture-catalog/new-entry --openclawFiles (1)
SKILL.md
3.2 KB
Create New Registry Entry
Guide the user through creating a properly structured registry entry.
Arguments
$1- Element type: component, software-system, data-concept, data-aggregate, data-entity, domain-event, api-endpoint, etc.$2+- Element name (can have spaces)
If arguments not provided, ask the user:
- What type of element?
- What is the element name?
- Which domain does it belong to?
Element Type to Folder Mapping
| Type | Folder |
|---|---|
| domain | registry-v2/3-application/domains/ |
| component | registry-v2/3-application/components/ |
| software-system | registry-v2/3-application/software-systems/ |
| software-subsystem | registry-v2/3-application/software-subsystems/ |
| api-endpoint | registry-v2/3-application/api-endpoints/ |
| api-contract | registry-v2/3-application/api-contracts/ |
| domain-event | registry-v2/3-application/domain-events/ |
| data-concept | registry-v2/3-application/data-concepts/ |
| data-aggregate | registry-v2/3-application/data-aggregates/ |
| data-entity | registry-v2/3-application/data-entities/ |
| capability | registry-v2/2-organization/capabilities/ |
| process | registry-v2/2-organization/processes/ |
| market-segment | registry-v2/1-business/market-segments/ |
| product | registry-v2/1-business/products/ |
| business-service | registry-v2/1-business/business-services/ |
| infra-node | registry-v2/4-technology/infra-nodes/ |
| cloud-service | registry-v2/4-technology/cloud-services/ |
Workflow
- Determine element type and target folder
- Read
_template.mdin the target folder for structure - Read 1-2 existing entries in target folder for pattern reference
- Create filename: kebab-case of name (e.g., "Payment Record" -> "payment-record.md")
- Fill frontmatter:
- name: [provided name]
- owner: TBD
- status: draft
- [type-specific fields and relationships from template]
- Write file to correct folder
- Run validation:
python scripts/validate.py
Response Format
**Created:** registry-v2/3-application/data-entities/payment-record.md
**Frontmatter:**
---
type: data-entity
name: Payment Record
owner: TBD
status: draft
parent_data_aggregate: TBD
---
**Next Steps:**
1. Fill in TBD fields (owner, parent_data_aggregate)
2. Add description in the body
3. Run /validate to verify
Would you like me to help fill in any of the TBD fields?
Domain-Specific Fields
For data elements (concepts, aggregates, entities), also include:
- Relationship to parent element (data concept -> aggregate -> entity chain)
- classification: internal/business-confidential/pii
For software elements (systems, subsystems), also include:
- sourcing: in-house/vendor/hybrid
- vendor: (if vendor)
- realizes_component: Which component this system supports
Notes
- Always use kebab-case for filenames
- Mark unknown fields as TBD rather than guessing
- Run validation after creation to catch issues early
- Suggest wiring relationships as a follow-up action
Source
git clone https://github.com/ea-toolkit/architecture-catalog/blob/main/.claude/skills/new-entry/SKILL.mdView on GitHub Overview
This skill walks users through creating a properly structured registry entry with a guided wizard. It supports components, data concepts, data aggregates, data entities, domain events, API endpoints, and more, mapping each entry to the correct registry folder. The process leverages folder templates, frontmatter conventions, and a final validation step.
How This Skill Works
The wizard determines the element type and target folder, reads the folder's _template.md to understand the required structure, and references existing entries for pattern consistency. It then creates a kebab-cased filename, fills frontmatter fields (type, name, owner, status, and type-specific relationships), writes the file to the correct registry folder, and runs the validation script to ensure correctness.
When to Use It
- You are creating a new registry entry for a new ArchiMate element (e.g., component, data-entity)
- You need to place the entry into the correct registry-v2 folder based on its type
- You want the frontmatter to follow the project pattern and to perform immediate validation
- You require a consistent kebab-case filename derived from the element name
- You want to capture TBD fields explicitly and avoid guessing
Quick Start
- Step 1: Run the wizard with the element type and name (e.g., component Payment Processor)
- Step 2: Answer prompts for domain and any required relationships; review suggested template structure
- Step 3: Accept defaults or fill in TBD fields, then run the validation command
Best Practices
- Always use kebab-case for filenames and avoid spaces
- Review 1-2 existing entries in the target folder to mirror style and fields
- Mark unknown fields as TBD and avoid guessing values
- Fill in owner and parent relationships where possible before final review
- Run the validation script (python scripts/validate.py) after creating the file
Example Use Cases
- Create a new component Payment Processor mapped to registry-v2/3-application/components/
- Add a data-entity Payment Record under registry-v2/3-application/data-entities/
- Create an API endpoint /payments under registry-v2/3-application/api-endpoints/
- Register a domain-event PaymentCompleted under registry-v2/3-application/domain-events/
- Define a data-concept CustomerProfile under registry-v2/3-application/data-concepts/
Frequently Asked Questions
Add this skill to your agents
