librefang-registry/docs/content-guide.md

Content Guide

Guidelines for contributing content to the LibreFang Registry.

Naming Conventions

• Use lowercase, hyphenated names: my-agent, web-scraper, code-reviewer.
• Agent/hand/skill directory names must match their name/id field in the TOML.
• Provider and integration filenames must match their id field.

Writing Descriptions

• Keep descriptions to 1-2 sentences. Lead with a verb.
• Good: "Analyzes pull requests and suggests improvements."
• Bad: "This is an agent that can be used to analyze pull requests."

System Prompts (Agents & Hands)

• Start with a clear role statement: "You are X, responsible for Y."
• Include specific instructions on behavior, not vague aspirations.
• Define what the agent should not do (scope boundaries).
• List tools it should use and when.
• Aim for 100-500 words for agents, up to 1000 for complex hands.
• Avoid repeating information already in the TOML metadata.

Agent vs Hand vs Skill

Type	Use When
Agent	Conversational, general-purpose, stateless Q&A or analysis.
Hand	Multi-step workflow requiring tools (shell, files, APIs). Has settings, dashboard, requirements.
Skill	Single focused task with defined inputs/outputs. Prompt-only or a short script.

• If it needs shell_exec or external tools, it is probably a hand.
• If it is a reusable prompt template with parameters, it is a skill.
• If it is a conversational assistant for a domain, it is an agent.

Provider Entries

• Include all models the provider offers that support chat completions.
• Use accurate input_cost_per_m / output_cost_per_m (USD per million tokens).
• Set tier honestly: frontier is reserved for the most capable models.
• Always include context_window and max_output_tokens from official docs.

General Tips

• Run make validate before submitting.
• Run make fmt if you have taplo installed to keep TOML formatting consistent.
• Check schema.toml for the full field reference.
• Test scaffold output: make new-agent NAME=test-agent, verify, then delete.