Contributing Agent Skills

Agent skills are workflow contracts. Keep them small, explicit, and safe.

Required Structure

Each skill lives under skills/<name>/SKILL.md.

The skill must include:

• YAML frontmatter with name, description, and metadata.short-description;
• Use When;
• Required Context;
• Workflow;
• Security Boundary;
• Verification;
• Output.

Rules

• Do not reference machine-local absolute paths.
• Prefer hosted MCP for external users.
• Do not instruct agents to use mutation tools unless the workflow is explicitly internal.
• Do not ask agents to render AI-UI descriptors without Zod validation.
• Do not tell agents to read arbitrary filesystem paths from model input.
• Put long optional context in references/ and link it from SKILL.md.
• Keep SKILL.md concise enough for an agent to load at trigger time.

Public Skill Format

Public skills use the same folder shape:

skills/<name>/
├── SKILL.md
└── references/

The docs site publishes both raw folders and .skill archives. Keep the source folder, raw download, archive, and skill pack manifest aligned.

Documentation Requirements

When adding or changing a public skill, update every distribution surface:

Install Guidance Content

Every public skill must document:

• which tasks trigger the skill;
• whether MCP is required;
• where the skill can be downloaded;
• raw folder versus .skill archive usage;
• client-specific install notes if needed;
• verification steps after installation;
• security boundaries and secret-handling rules.

Review Checklist

• Skill names the correct package/docs.
• Skill frontmatter has a clear trigger-focused description.
• Skill tells the agent to search before inventing.
• Skill prevents source leakage from hosted MCP.
• Skill has a verification step.
• Skill points to External Developers when used by outside developers.