synapsync/cognitive-register

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:

1. Cognitive name: The identifier (convert to kebab-case)
2. Cognitive type: skill, agent, prompt, workflow, or tool
3. Content: The actual cognitive content (inline, previous message, or ask)
4. 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:

1. Read registry.json
2. Search for the name in the cognitives array
3. 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": "[email protected]"
  },
  "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:

1. Read current registry.json
2. Increment totalCognitives by 1
3. 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:

1. The cognitive type itself (e.g., skill, agent)
2. Key topics from the content (e.g., planning, git, testing)
3. The category (e.g., devops, frontend)
4. Action verbs from the purpose (e.g., automation, analysis)
5. 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

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

During Registration

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

After Registration

1. Verify registry.json: Read it back to confirm the entry was added correctly
2. Confirm totalCognitives: Ensure count matches array length
3. 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

1. No automated validation CI: Validation is performed at registration time by the AI, not by a CI pipeline
2. No version bumping: Currently registers new cognitives at 1.0.0. Version updates require manual intervention
3. No dependency resolution: Does not check if referenced skills/agents in content actually exist
4. 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:

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

Example: Registering an Agent

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

AI executes:

1. Parse: name=deploy-automator, type=agent, category=devops (inferred)
2. Check registry.json → no duplicate found
3. Create cognitives/agents/devops/deploy-automator/
4. Write cognitives/agents/devops/deploy-automator/deploy-automator.md (note: agents use {name}.md)
5. Write cognitives/agents/devops/deploy-automator/manifest.json with "file": "deploy-automator.md"
6. Update registry.json
7. Confirm registration

Version History

• 1.0 (2026-01-28): Initial release with full registration workflow for all cognitive types