# skill-forge

> Builds precise production-ready custom Agent Skills following AgentSkills.io guidelines. Use when user requests to create, refine or package Skills

- Author: Nicolas Embleton
- Repository: Alcyone-Labs/agent-skills
- Version: 20260205101358
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Alcyone-Labs/agent-skills
- Web: https://mule.run/skillshub/@@Alcyone-Labs/agent-skills~skill-forge:20260205101358

---

---
name: skill-forge
description: Builds precise production-ready custom Agent Skills following AgentSkills.io guidelines. Use when user requests to create, refine or package Skills
references:
  - core-structure
  - build-patterns
  - install-script
---

# SkillForge

Expert AgentSkills.io architect. ONLY create, refine, package perfect custom Skills per official guidelines. Capture elite knowledge in references/.

## When to Apply

- User: "build a skill for X" "create skill about Y" "distill current session into a skill" "turn agent into skill" "package as skill"
- Extract nuanced facts/patterns too dense for single manifest

## Non-Negotiable, Golden Rules

- Target directory: `./skills/` by default.
- Additive behavior: ALWAYS preserve existing skills and commands in `./skills/`. DO NOT overwrite other skills.
- Structure:
  - `skills/skill-forge/SKILL.md` (CAPITALIZED)
  - `skills/skill-forge/README.md`
  - `skills/skill-forge/commands/opencode/skill-forge.md`
  - `skills/skill-forge/commands/gemini/skill-forge.toml`
  - `skills/skill-forge/commands/droid/skill-forge.md`
  - `skills/skill-forge/install.sh` (Single root installer for ALL skills)
- Folder: kebab-case.
- SKILL.md YAML first: name, description, references[].
- NO lowercase skill.md, NO colons in description.
- references/ MANDATORY: README.md, api.md, configuration.md, patterns.md, gotchas.md per topic.
- commands/
  - opencode/{skill-name}.md (OpenCode slash command)
  - gemini/{skill-name}.toml (Gemini CLI command)
  - droid/{skill-name}.md (FactoryAI Droid command)
- install.sh MUST be a copy of `references/install-script/template.sh`. ONLY update the `REPO_URL` constant.
- Supports `--self`, `--global`/`--local`.
- Supports selective flags: `--opencode`, `--gemini`, `--claude`, `--droid` (`--factory`), `--agents`, `--antigravity`.
- Defaults to interactive mode if no flags are provided.
- Interactive mode prompts for scope (Global/Local), agent selection (toggle menu), and skill selection (toggle menu).
- Automatically scans `skill/` directory for available skills.
- Uses dynamic `PROJECT_NAME` based on directory if not set.
- Interactive mode prompts to update `.gitignore` for local installs.
- Verbatim APIs/configs from docs.
- Examples: 2-3 input/output clusters.
- Max info density: bullets > paragraphs, sacrifice grammar for facts.

## Workflow Decision Tree

```
Request: create or refine skill for [topic]
A. Clarify scope
   - skill name, repo URL, target platforms
   - check if ./skill-forge exists; prepare for additive update
B. Research
   - APIs, configs, lifecycle, known issues
C. Design
   - description (<=200 chars, no colons)
   - references/{topic} layout
D. Write references/ under skill-forge/skill/{skill-name}/
   - README.md: overview, when to use, decision tree
   - api.md: verbatim signatures/types
   - configuration.md: schemas/keys/wiring
   - patterns.md: multi-step implementations
   - gotchas.md: pitfalls/limitations
E. Assemble under ./skills/
   - {skill-name}/SKILL.md: YAML + rules + workflow + examples
   - {skill-name}/README.md: High-level overview
  - commands/opencode/{skill-name}.md: OpenCode command template
  - commands/gemini/{skill-name}.toml: Gemini CLI command template
  - commands/droid/{skill-name}.md: FactoryAI Droid command template
   - install.sh: Multi-Skill Installer Pattern (Update or create at root)
Result: Updated ./skills/ tree with new skill/command added
```

## References

- **references/core-structure/README.md**: Folder layout, SKILL.md YAML schema, command format. Provides the skeleton every skill must follow. Check before creating new skills.
- **references/build-patterns/README.md**: When to split references/, 5-file topic set, A-E workflow, best practices. Prevents bloated SKILL.md and ensures consistent structure.
- **references/install-script/template.sh**: Multi-Skill Installer Template. Supports interactive mode, selective agent targeting, and gitignore updates. MUST use as base for all generated `install.sh` files (update `REPO_URL`).

## Examples

**Input:** Build skill for Chrome MV3 extensions  
**Output:** skill/chrome-mv3/

- SKILL.md: workflow for manifest service workers
- references/mv3-lifecycle/README.md: decision tree
- references/mv3-lifecycle/api.md: chrome.runtime.onInstalled etc
- references/persistent-storage/gotchas.md: no persistent globals

**Input:** Package TypeScript skill with install  
**Output:** Generated install.sh using the Multi-Skill Installer Template from references/install-script/template.sh. Supports `--self`, `--global`, `--local`, and selective flags like `--claude`.

**Input:** Refine existing agent md to skill  
**Output:** Parse, extract to structured refs, command, install