skillsmith

Forge, retune, and refactor opencode agent skills through a repeatable six-step process.

1|2|Updated Nov 25, 2017
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill skillsmith-asarchami
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: skillsmith
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/skillsmith
Command: npx skills add https://github.com/asarchami/dotfiles --skill skillsmith-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing agent skills that fire reliably and behave predictably is hard: descriptions fail to trigger, steps end prematurely, and bodies sprawl with stale or duplicated content. This Skill provides one repeatable process for creating, tuning, and repairing opencode skills so the agent follows the same process every run. ## Core Features & Use Cases - Three work shapes: Forge a new skill from scratch, retune an existing skill with a targeted change, or refactor a misbehaving skill that won't fire, rushes, sprawls, or drifts. - Harness validation: Enforces opencode mechanics including name regex rules, discovery paths, frontmatter fields, and permission checks via built-in harness and load-failure checklists. - Failure-mode diagnosis: Maps symptoms like premature completion, duplication, sediment, no-ops, and negation to specific cures defined in the bundled glossary. - Use Case: You wrote a skill that the agent never invokes. Run the refactor flow to sharpen the description's leading word, verify the name matches its folder, and confirm it appears in a fresh session's skill list. ## Quick Start Ask the agent to use the skillsmith skill to forge a new opencode skill for your desired behavior, starting with its questioning step.

Frequently Asked Questions about skillsmith

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an opencode skill that the agent actually invokes?

Place a SKILL.md file at a recognized discovery path such as .opencode/skills/<name>/, give it a name matching the folder and the regex ^[a-z0-9]+(-[a-z0-9]+)*$, and write a description with one trigger per branch. Then verify it appears in the skill tool in a fresh session.

How to fix an agent skill that won't fire?

Check that SKILL.md is spelled in all caps, frontmatter includes name and description, the name is unique across all discovery locations, and no permission.skill rule denies it. Then sharpen the description's leading word and keep one trigger per branch.

What frontmatter fields does opencode support in SKILL.md?

opencode recognizes name, description, license, compatibility, and metadata. Unknown fields are ignored, and disable-model-invocation does nothing in opencode; it is kept only for Claude or agent portability.

Why does my agent skill rush through steps before finishing?

This is premature completion caused by a vague completion criterion. Sharpen the criterion so done is clearly distinguishable from not-done; only if it stays fuzzy should you hide post-completion steps by splitting the sequence.

Can I make an opencode skill user-invoked only?

opencode loads every skill's name and description into the skill tool, so there is no true user-only state. Write the description as a human-facing one-liner with no triggers, or use a permission.skill deny rule to hide it entirely.