Hermes Figma Prompt Hub

Standalone Figma/Hermes prompt hub scaffold for designing, versioning, and validating structured prompt assets outside the Hermes core tree.

This project was split out from a Hermes core-tree integration proposal. It is intended to be used as an external project or plugin-style companion repository.

Contributors wanted

This repository is looking for contributors who want to help turn the scaffold into a useful Figma/Hermes MCP integration.

Good first areas:

• Build a Figma API importer that converts PROMPT/<id> frames into prompt JSON.

• Implement mcp/server.py with tools for listing, validating, and exporting prompts.

• Add prompt examples and eval cases under prompts/raw and evals/cases.

• Improve docs for Hermes MCP setup and Figma token handling.

• Add tests for schema validation and future importer behavior.

Start here:

• Read CONTRIBUTING.md.

• Pick an item from ROADMAP.md.

• Open or claim an issue with the good first issue or help wanted label.

Related MCP server: Figma MCP Server

Sponsor development

If this project is useful to you, you can sponsor ongoing development through GitHub Sponsors:

https://opencollective.com/hermes-figma-prompt-hub

https://github.com/sponsors/jozrftamson

OpenCollective is the recommended option for transparent project funding. GitHub Sponsors, Buy Me a Coffee, and Ko-fi are also documented in SPONSORING.md.

Sponsorship helps fund Figma API importer work, MCP server development, prompt validation, documentation, and contributor support.

Installation

git clone https://github.com/jozrftamson/hermes-figma-prompt-hub.git
cd hermes-figma-prompt-hub
python3 -m venv .venv
. .venv/bin/activate
pip install jsonschema

Or install pinned project dependencies:

pip install -r requirements.txt

Validate the included example prompt:

python scripts/validate_prompt.py prompts/raw/nous-central-v1.json

Validate the full repository:

python scripts/validate_repo.py

Create or refresh the scaffold files in the current project:

python install/scaffold.py

To scaffold into another directory:

python install/scaffold.py /path/to/figma-hermes-prompt-hub

Figma token and API configuration

Create a Figma personal access token in Figma and keep it outside source control:

export FIGMA_ACCESS_TOKEN="figd_..."
export FIGMA_FILE_KEY="your-file-key"

The current scaffold defines the prompt contract and validation format. A Figma sync command can read frames named PROMPT/<id> and map layers using prompts/figma-layer-contract.txt.

Expected Figma frame/layer contract:

Figma Layer Contract (Frame: PROMPT/<id>)
00_system
01_developer
02_user_template
03_output_format
04_tool_policy
05_context_source_<name>
10_guardrail_<n>
11_constraint_<n>
12_style_rule_<n>
20_example_in_<n>
21_example_out_<n>
22_example_note_<n>
30_variable_<name>
40_test_case_<n>
50_expected_output_<n>
80_changelog_<version>
90_eval_must_include_<n>
91_eval_must_not_include_<n>
92_eval_check_<n>

Hermes MCP configuration

Use Hermes' external MCP configuration path instead of adding vendor-specific code to the Hermes repository.

Example MCP server entry:

{
  "mcp_servers": {
    "figma-prompt-hub": {
      "command": "python",
      "args": [
        "/absolute/path/to/hermes-figma-prompt-hub/mcp/server.py"
      ],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}",
        "FIGMA_FILE_KEY": "${FIGMA_FILE_KEY}"
      }
    }
  }
}

mcp/server.py is intentionally left as an integration point. Keep Figma API access and Hermes-specific MCP wiring in this external repository.

Example prompt workflow

1. Design a Figma frame named PROMPT/nous-central-v1.

2. Add text layers matching prompts/figma-layer-contract.txt.

3. Export or sync the frame into prompts/raw/nous-central-v1.json.

4. Validate the prompt:

python scripts/validate_prompt.py prompts/raw/nous-central-v1.json

5. Use the validated prompt JSON from Hermes or an MCP tool.

Prompt format

Prompt JSON files must match prompts/schema/prompt.schema.json:

{
  "id": "nous-central-v1",
  "version": "0.2.0",
  "status": "active",
  "category": "general-assistant",
  "tags": ["hermes", "figma", "prompt-hub"],
  "model": "gpt-4.1",
  "temperature": 0.2,
  "system": "Du bist ein präziser Assistent.",
  "developer": "Antwort kurz, korrekt, ohne Floskeln. Markiere Unsicherheit klar und verwende nur den gegebenen Kontext.",
  "user_template": "Kontext: {{context}}\nAufgabe: {{task}}\nGewünschtes Format: {{format}}",
  "output_format": {
    "type": "json",
    "instructions": "Return valid JSON with summary, reasoning_notes and next_actions."
  },
  "variables": ["context", "task", "format"],
  "context_sources": [
    {
      "name": "figma_frame",
      "type": "figma",
      "required": false,
      "description": "Optional Figma frame or layer context for design-aware prompts."
    }
  ],
  "tools": [
    {
      "name": "mcp",
      "allowed": true,
      "policy": "Use MCP tools for prompt listing, validation and export."
    }
  ],
  "guardrails": ["Keine erfundenen Fakten", "Bei Unsicherheit klar markieren"],
  "constraints": ["Use only supplied context.", "Keep output concise."],
  "style_rules": ["Use direct language.", "Prefer actionable next steps."],
  "few_shots": [
    {
      "input": "task=Summarize X",
      "output": "{\"summary\":\"Kurzfassung ...\",\"next_actions\":[\"Review copy\"]}",
      "notes": "Shows compact JSON output."
    }
  ],
  "changelog": [
    {
      "version": "0.2.0",
      "changes": ["Added output format, tools, constraints and eval checks"]
    }
  ],
  "eval": {
    "must_include": ["summary", "next_actions"],
    "must_not_include": ["Great question", "As an AI"],
    "checks": [
      {
        "name": "valid_json_output",
        "type": "json_schema",
        "value": {
          "type": "object",
          "required": ["summary", "next_actions"]
        }
      }
    ]
  }
}

Supported prompt extensions:

• status: draft, active or deprecated lifecycle state.

• category and tags: prompt grouping for search and catalog views.

• model and temperature: recommended runtime defaults.

• output_format: expected text, markdown or JSON response contract.

• context_sources: named inputs such as Figma frames, user notes or documents.

• tools: allowed tool names and usage policies.

• constraints: hard behavioral limits.

• style_rules: tone and formatting preferences.

• few_shots[].notes: explanation for examples.

• changelog: prompt version history.

• eval.checks: structured checks such as contains, not_contains, regex, json_schema and max_length.

Development automation

This repository includes automation for ongoing development and collaborator onboarding:

• CI: validates prompt JSON, compiles Python files, and tests scaffold output on pushes and PRs.

• Issue welcome: comments on new issues with contributor links and next steps.

• PR welcome: comments on new PRs with the review checklist.

• Collaboration digest: manually creates a GitHub issue summarizing current contributor opportunities.

• Prompt catalog: generates docs/prompt-catalog.md from prompts/raw/*.json.

• Figma contract check: keeps the layer contract, README, and fixtures synchronized.

• Good first issue seeding: creates small contributor-friendly issues monthly.

• Stale issue ping: reminds inactive issues after 30 days without closing them.

• Contributor recognition: records merged PR contributors in CONTRIBUTORS.md.

• Schema release suggestion: opens a release-planning issue after schema changes.

• Sponsor and contributor monthly update: creates a monthly update issue for sponsors and collaborators.

Local commands:

python scripts/validate_repo.py
python scripts/generate_collaboration_digest.py
python scripts/generate_prompt_catalog.py
python scripts/check_figma_contract.py

See COLLABORATION.md, HUMAN_COLLABORATORS.md, docs/prompt-catalog.md, and docs/outreach/templates.md for outreach templates, collaborator roles, and maintainer routines.