Evan Hu
a8b7c9d08b
Community docs: - CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - SECURITY.md (vulnerability reporting policy) - CHANGELOG.md (initial release notes) - CODEOWNERS (per-type review ownership) GitHub config: - Issue templates: bug-report, pricing-correction, documentation - FUNDING.yml (GitHub Sponsors) Validation enhancements: - Cross-reference check: hand [[requires]] → integration existence - Routing alias collisions as warnings (errors with --strict) - --strict flag to promote warnings to errors - --type filter to validate single content type - CI: add taplo format check and lychee link check jobs Developer experience: - Makefile with validate, fmt, and scaffold targets - Scaffold templates for all 5 content types - .pre-commit-config.yaml (trailing whitespace, TOML check, validate) - docs/content-guide.md (naming, descriptions, prompts, decision guide) Content quality: - schema.toml: add last_verified field for model pricing - CONTRIBUTING.md: add pricing verification guide with source links
51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
# 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.
|