echobot-skill-authoring

EchoBot Skill Authoring

Create or revise repository-local skills that EchoBot can discover and activate.

Authoring goals

• Put project-specific skills under skills/<skill-name>/.
• Use lowercase kebab-case for the folder name and the name frontmatter field.
• Keep frontmatter minimal. EchoBot routing reads name and description from SKILL.md.
• Keep name as a single-line value. description may be a single line or a YAML block scalar with > or |.
• Write description as the trigger surface: what the skill does, when to use it, and what kinds of user requests or contexts should activate it. Include likely request phrasing when that improves triggering.
• Keep the main body procedural and concise. Move deeper material into small files under references/ or scripts/.
• Design for lazy loading. After activation, EchoBot exposes the body plus a resource summary. It does not auto-load bundled files.
• Only put text resources that an agent may need to read into references/, scripts/, or agents/. read_skill_resource only reads UTF-8 text files.
• Use assets/ for templates or binary output artifacts, not for essential instructions.
• Do not treat agents/openai.yaml as required. Current EchoBot discovery ignores it.
• Avoid extra docs like README.md or changelog files inside a skill unless the runtime truly needs them.

Frontmatter checklist

• Keep name stable and specific. Renaming a skill changes explicit /skill-name and $skill-name activation.
• Make description concrete. Good descriptions say both the task and the trigger context.
• Do not put "when to use" guidance only in the body. The body is loaded after activation.
• EchoBot currently ignores extra frontmatter keys. The validator is more permissive for compatibility, but project-local skills should usually keep only name and description.

Resource layout

skills/<skill-name>/
|-- SKILL.md
|-- references/   # short, focused UTF-8 docs loaded on demand
|-- scripts/      # executable helpers or deterministic workflows
|-- assets/       # templates or binary resources not meant for context loading
`-- agents/       # optional helper prompts or agent-specific text resources