cognitive-register by synapsync/synapse

Purpose

Automate the registration of new cognitives into the SynapSync Registry, ensuring every entry follows the exact structure, naming conventions, manifest schema, and registry index format — with zero tolerance for inconsistencies.

When to Use This Skill

User says "GUARDA X SKILL": Register a new skill with its content
User says "GUARDA X AGENT": Register a new agent with its content
User says "GUARDA X PROMPT": Register a new prompt with its content
User says "GUARDA X WORKFLOW": Register a new workflow with its content
User says "GUARDA X TOOL": Register a new tool with its content
User says "REGISTRA" or "AGREGA": Same as above, alternative trigger words
User provides cognitive content and asks to save it: Infer type from content and register
English equivalents: "SAVE X SKILL", "REGISTER X AGENT", "ADD X PROMPT"

Trigger Pattern Recognition

The skill responds to these patterns (case-insensitive, Spanish or English):

GUARDA [el|la|un|una]? {name} [como]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL
REGISTRA [el|la|un|una]? {name} [como]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL
AGREGA [el|la|un|una]? {name} [como]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL
SAVE {name} [as]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL
REGISTER {name} [as]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL
ADD {name} [as|to]? SKILL|AGENT|PROMPT|WORKFLOW|TOOL

If the user provides the cognitive content inline or in a previous message, use that content directly. If no content is provided, ask the user for it.

Registry Structure (Source of Truth)

synapse-registry/
├── registry.json                          # Central index — MUST be updated
├── cognitives/                            # Public registry content
│   ├── skills/{category}/{name}/
│   │   ├── manifest.json                  # Metadata
│   │   ├── SKILL.md                       # Content file
│   │   └── assets/                        # Optional templates/schemas
│   ├── agents/{category}/{name}/
│   │   ├── manifest.json
│   │   └── {name}.md                      # Content file (uses cognitive name)
│   ├── prompts/{category}/{name}/
│   │   ├── manifest.json
│   │   └── PROMPT.md
│   ├── workflows/{category}/{name}/
│   │   ├── manifest.json
│   │   └── WORKFLOW.yaml
│   └── tools/{category}/{name}/
│       ├── manifest.json
│       └── TOOL.md
└── core/                                  # Internal tooling (not published)
    └── register/                          # This skill

Valid Categories

Category	Use For
`general`	General-purpose, meta-tools, internal tooling
`frontend`	UI, React, CSS, components
`backend`	APIs, servers, backend services
`database`	Database queries, migrations, ORMs
`devops`	CI/CD, infrastructure, deployment
`security`	Security analysis, vulnerability scanning
`testing`	Testing strategies, QA automation
`analytics`	Data analysis, research, benchmarking
`automation`	Task automation, workflows
`integrations`	External services (Supabase, Stripe, etc.)
`planning`	Project planning, SDLC, requirements, architecture

If the cognitive doesn't clearly fit a category, default to general. If the user specifies a category, use it even if it's new — the registry supports extensibility.

Valid Providers

claude, openai, cursor, windsurf, copilot, gemini, codex

Default: All providers unless the cognitive is provider-specific (e.g., an agent using Claude-only features).

Cognitive Type → Content File Mapping

Type	Content File	Notes
skill	`SKILL.md`	Markdown with YAML frontmatter
agent	`{name}.md`	Named after the cognitive, YAML frontmatter
prompt	`PROMPT.md`	Markdown with YAML frontmatter
workflow	`WORKFLOW.yaml`	Pure YAML definition
tool	`TOOL.md`	Markdown with YAML frontmatter

Registration Workflow

Step 1: Parse the Request

Extract from the user's message:

Cognitive name: The identifier (convert to kebab-case)
Cognitive type: skill, agent, prompt, workflow, or tool
Content: The actual cognitive content (inline, previous message, or ask)
Category: Infer from content/context or ask the user

Name normalization rules:

Convert to lowercase
Replace spaces with hyphens
Remove special characters except hyphens
Examples: "Project Planner" → project-planner, "API Error Handler" → api-error-handler

Step 2: Validate Uniqueness

Before creating anything, check that no cognitive with the same name exists:

Read registry.json
Search for the name in the cognitives array
If a duplicate exists, inform the user and ask how to proceed:
- Update the existing cognitive (bump version)
- Choose a different name
- Cancel

Step 3: Create Directory Structure

mkdir -p cognitives/{type}s/{category}/{name}

The directory follows the pattern: cognitives/{type}s/{category}/{name}/

Examples:

cognitives/skills/general/my-skill/
cognitives/agents/devops/deploy-manager/
cognitives/prompts/frontend/component-generator/

Step 4: Create Content File

Write the cognitive content to the appropriate file:

skill → cognitives/{type}s/{category}/{name}/SKILL.md
agent → cognitives/{type}s/{category}/{name}/{name}.md
prompt → cognitives/{type}s/{category}/{name}/PROMPT.md
workflow → cognitives/{type}s/{category}/{name}/WORKFLOW.yaml
tool → cognitives/{type}s/{category}/{name}/TOOL.md

If the user provided content with YAML frontmatter, use it as-is. If not, ensure the content has proper frontmatter before writing.

Step 5: Create manifest.json

Every cognitive MUST have a manifest.json in its directory:

{
  "$schema": "https://synapsync.dev/schemas/cognitive-manifest.json",
  "name": "{name}",
  "type": "{type}",
  "version": "1.0.0",
  "description": "{max 100 chars — extracted from content or user input}",
  "author": {
    "name": "SynapSync",
    "url": "https://github.com/SynapSync",
    "email": "hello@synapsync.dev"
  },
  "license": "Apache-2.0",
  "category": "{category}",
  "tags": ["{tag1}", "{tag2}", "...max 10 tags"],
  "providers": ["claude", "openai", "cursor", "windsurf", "copilot", "gemini"],
  "file": "{content-file-name}",
  "repository": {
    "type": "git",
    "url": "https://github.com/SynapSync/skills-registry"
  },
  "homepage": "https://synapsync.dev/cognitives/{name}",
  "createdAt": "{ISO 8601 current date}T00:00:00Z",
  "updatedAt": "{ISO 8601 current date}T00:00:00Z"
}

Field extraction rules:

name: From the parsed request (kebab-case)
description: From YAML frontmatter description field, trimmed to 100 chars. Remove trigger text — only keep the functional description
tags: Infer from content topics, category, and type. Maximum 10 tags
providers: Default to all providers unless content indicates provider-specific features
file: Based on type mapping (see table above)
createdAt/updatedAt: Current date in ISO 8601

Step 6: Update registry.json

Add the new cognitive to registry.json:

Read current registry.json
Increment totalCognitives by 1
Append a new entry to the cognitives array:

{
  "name": "{name}",
  "type": "{type}",
  "version": "1.0.0",
  "description": "{same as manifest description}",
  "author": "synapsync",
  "category": "{category}",
  "tags": ["{same tags as manifest}"],
  "providers": ["{same providers as manifest}"],
  "downloads": 0,
  "path": "cognitives/{type}s/{category}/{name}"
}

Critical: The registry.json entry uses "author" as a flat string (not an object), unlike manifest.json which uses an author object.

Step 7: Confirmation

After successful registration, report:

Created files and their paths
Updated registry.json with new count
The cognitive's full path in the registry

Validation Rules (Enforced on Every Registration)

These rules are non-negotiable. If any fails, fix it before completing:

Rule	Requirement
Unique name	No other cognitive in `registry.json` has the same name
Valid manifest.json	All required fields present, matches schema
Content file exists	The file referenced in `manifest.file` exists
Frontmatter consistency	Frontmatter `name` matches `manifest.name`
Valid category	Category is from the valid categories list
Tags limit	Maximum 10 tags
Description length	Maximum 100 characters in manifest/registry description
Name format	Lowercase, hyphens only, no spaces or special chars
Version format	Semantic versioning (e.g., `1.0.0`)
Path format	`cognitives/{type}s/{category}/{name}` matches actual directory
registry.json sync	`totalCognitives` count matches actual array length

Naming Convention Reference

Pattern	When to Use	Examples
`{technology}`	Generic technology skill	`typescript`, `react-hooks`
`{tech}-{feature}`	Technology + specific feature	`react-testing`, `node-logging`
`{framework}-{component}`	Framework + component type	`nextjs-api`, `express-middleware`
`{action}-{target}`	Action-oriented naming	`skill-creator`, `code-reviewer`
`{domain}-{function}`	Domain + function	`auth-validator`, `data-migrator`

Bad names: utils, helpers, common, misc, project1, test, new-skill Good names: cognitive-registrar, api-error-handler, feature-branch-manager

Critical Patterns

Pattern 1: Always Read Before Write

Before creating any file, read registry.json to verify:

The name doesn't already exist
The current totalCognitives count
The existing structure to maintain consistency

Pattern 2: Description Extraction

When extracting a description from content frontmatter:

Remove the Trigger: portion — descriptions should be functional, not trigger-based
Trim to 100 characters maximum
Make it action-oriented: "Creates...", "Manages...", "Analyzes..."

Example:

# Frontmatter says:
description: >
  Comprehensive project planning framework with structured analysis, planning, and execution phases.
  Trigger: When planning a new feature...

# manifest.json/registry.json gets:
"description": "Comprehensive project planning framework with analysis, planning, and execution phases"

Pattern 3: Tag Inference

Generate tags by analyzing:

The cognitive type itself (e.g., skill, agent)
Key topics from the content (e.g., planning, git, testing)
The category (e.g., devops, frontend)
Action verbs from the purpose (e.g., automation, analysis)
Technologies mentioned (e.g., react, typescript, docker)

Keep tags lowercase, hyphenated, and meaningful. Avoid redundant tags (don't add skill tag to a skill unless it's a meta-skill about skills).

Pattern 4: Provider Detection

Default to all providers. Restrict only when:

Content uses provider-specific syntax (e.g., Claude XML tags, OpenAI function calling)
The agent definition uses provider-specific fields (e.g., model: sonnet)
The user explicitly states provider restrictions

Pattern 5: Atomic Registration

All three artifacts (content file, manifest.json, registry.json) must be created/updated in a single operation. Never leave the registry in a partial state:

If content file creation fails, don't update registry.json
If manifest.json creation fails, clean up the content file
Always verify the final state after all writes

Pattern 6: Category Directory Creation

If the category directory doesn't exist under the type directory, create it:

# If cognitives/skills/planning/ doesn't exist yet
mkdir -p cognitives/skills/planning/project-planner

This is valid — the registry supports new categories as the ecosystem grows.

Best Practices

Before Registration

Verify the cognitive content is complete: Don't register stubs or placeholders
Check for duplicates: Search by name AND by similar descriptions
Validate frontmatter: Ensure all required fields exist in the content file
Confirm category: If uncertain, ask the user

During Registration

Create files in order: Directory → Content file → manifest.json → registry.json
Use consistent dates: Same createdAt and updatedAt for new cognitives
Match descriptions: manifest.json and registry.json descriptions must be identical
Match tags and providers: manifest.json and registry.json must have identical arrays

After Registration

Verify registry.json: Read it back to confirm the entry was added correctly
Confirm totalCognitives: Ensure count matches array length
Report to user: List all created files and the registry path

Integration with Other Skills

With `skill-creator`

Use skill-creator to generate the SKILL.md content, then use cognitive-registrar to register it in the registry.

With `feature-branch-manager`

After registering a cognitive, use feature-branch-manager to commit the changes and create a PR.

Limitations

No automated validation CI: Validation is performed at registration time by the AI, not by a CI pipeline
No version bumping: Currently registers new cognitives at 1.0.0. Version updates require manual intervention
No dependency resolution: Does not check if referenced skills/agents in content actually exist
Single registry: Only manages the synapse-registry — does not publish to external registries

Troubleshooting

Issue: "Name already exists in registry"

Solution: Check registry.json for the existing entry. Offer the user options: update the existing cognitive (bump version), choose a different name, or cancel.

Issue: "Category directory doesn't exist"

Solution: This is normal for new categories. The mkdir -p command handles this automatically. The registry supports extensible categories.

Issue: "Content has no YAML frontmatter"

Solution: If the user provides raw content without frontmatter, generate the frontmatter based on the cognitive name, type, and inferred metadata before writing the file.

Issue: "Description exceeds 100 characters"

Solution: Truncate intelligently — don't cut mid-word. Rephrase to be more concise while preserving meaning.

Issue: "registry.json totalCognitives is out of sync"

Solution: Count the actual entries in the cognitives array and set totalCognitives to match. Never trust the existing count — always recalculate.

Example: Registering a Skill

User says: GUARDA project-planner SKILL (with content provided)

AI executes:

Parse: name=project-planner, type=skill, category=planning (inferred from content)
Check registry.json → no duplicate found
Create cognitives/skills/planning/project-planner/
Write cognitives/skills/planning/project-planner/SKILL.md (user's content)
Write cognitives/skills/planning/project-planner/manifest.json
Update registry.json:
- totalCognitives: 2 → 3
- Add entry with "path": "cognitives/skills/planning/project-planner"
Confirm: "Registered project-planner skill in cognitives/skills/planning/project-planner/"

Example: Registering an Agent

User says: GUARDA deploy-automator AGENT (with content provided)