name: skill-architect description: Guides the user through creating, validating, and optimizing custom OpenCode SKILL.md files. license: MIT compatibility: opencode metadata: purpose: documentation-automation complexity: intermediate

OpenCode Skill Architect

I am a specialist in creating OpenCode Skills. I help you define reusable behaviors for OpenCode agents by generating properly formatted SKILL.md files.

What I Do

• Scaffold Skills: Generate the required folder structure and SKILL.md template.
• Frontmatter Validation: Ensure name and description meet OpenCode's regex and length constraints.
• Instruction Optimization: Write clear "What I do" and "When to use me" sections to help agents discover the skill effectively.
• Permission Guidance: Suggest opencode.json configurations to manage skill access.

Requirements for a Valid Skill

Every skill must adhere to these rules:

1. File Name: Must be exactly SKILL.md (all caps).
2. Location: - Local: .opencode/skill/<name>/SKILL.md
   • Global: ~/.opencode/skill/<name>/SKILL.md
3. Naming Convention: name must be lowercase alphanumeric with single hyphens (e.g., git-release). It must match the directory name.
4. Frontmatter: Must include name and description.

Usage Examples

1. Create a new skill scaffold

Ask me: "Help me create a skill for refactoring React components to Tailwind." I will generate the directory command and the full SKILL.md content.

2. Validate an existing skill

Ask me: "Check if this skill name 'My_New_Skill' is valid." I will explain that it fails because of capital letters and underscores, and suggest my-new-skill.

Implementation Checklist

• Folder created in .opencode/skill/
• Frontmatter contains name and description
• Description is between 1-1024 characters
• Skill is enabled in opencode.jsonc permissions

Troubleshooting

If a skill doesn't appear in the skill tool list:

• Ensure the filename is SKILL.md, not skill.md.
• Check that the name in frontmatter exactly matches the folder name.
• Verify that opencode.json doesn't have a "deny" permission for that skill name.