@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/sharing-skills/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sharing-skills
+description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository
+version: 1.0.0
+tags: [workflow, git]
+dependencies: []
+---
+
+# Sharing Skills
+
+## When to Use
+
+- When a skill is broadly useful and ready to be contributed upstream via pull request.
+
+## When NOT to Use
+
+- When the skill is project-specific, experimental, or contains sensitive information.
+
+## Overview
+
+Contribute skills from your local branch back to the upstream repository.
+
+**Workflow:** Branch → Edit/Create skill → Commit → Push → PR
+
+## When to Share
+
+**Share when:**
+
+- Skill applies broadly (not project-specific)
+- Pattern/technique others would benefit from
+- Well-tested and documented
+- Follows writing-skills guidelines
+
+**Keep personal when:**
+
+- Project-specific or organization-specific
+- Experimental or unstable
+- Contains sensitive information
+- Too narrow/niche for general use
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated
+- Working directory is `.opencode/skill/` (your project skills)
+- **REQUIRED:** Skill has been tested using writing-skills TDD process
+
+## Sharing Workflow
+
+### 1. Ensure You're on Main and Synced
+
+```bash
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main  # Push to your fork
+```
+
+### 2. Create Feature Branch
+
+```bash
+# Branch name: add-skillname-skill
+skill_name="your-skill-name"
+git checkout -b "add-${skill_name}-skill"
+```
+
+### 3. Create or Edit Skill
+
+```bash
+# Work on your skill in skills/
+# Create new skill or edit existing one
+# Skill should be in skills/category/skill-name/SKILL.md
+```
+
+### 4. Commit Changes
+
+```bash
+# Add and commit
+git add skills/your-skill-name/
+git commit -m "Add ${skill_name} skill
+
+$(cat <<'EOF'
+Brief description of what this skill does and why it's useful.
+
+Tested with: [describe testing approach]
+EOF
+)"
+```
+
+### 5. Push to Your Fork
+
+```bash
+git push -u origin "add-${skill_name}-skill"
+```
+
+### 6. Create Pull Request
+
+```bash
+# Create PR to upstream using gh CLI
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add ${skill_name} skill" \
+  --body "$(cat <<'EOF'
+## Summary
+Brief description of the skill and what problem it solves.
+
+## Testing
+Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
+
+## Context
+Any additional context about why this skill is needed and how it should be used.
+EOF
+)"
+```
+
+## Complete Example
+
+Here's a complete example of sharing a skill called "async-patterns":
+
+```bash
+# 1. Sync with upstream
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main
+
+# 2. Create branch
+git checkout -b "add-async-patterns-skill"
+
+# 3. Create/edit the skill
+# (Work on skills/async-patterns/SKILL.md)
+
+# 4. Commit
+git add skills/async-patterns/
+git commit -m "Add async-patterns skill
+
+Patterns for handling asynchronous operations in tests and application code.
+
+Tested with: Multiple pressure scenarios testing agent compliance."
+
+# 5. Push
+git push -u origin "add-async-patterns-skill"
+
+# 6. Create PR
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add async-patterns skill" \
+  --body "## Summary
+Patterns for handling asynchronous operations correctly in tests and application code.
+
+## Testing
+Tested with multiple application scenarios. Agents successfully apply patterns to new code.
+
+## Context
+Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
+```
+
+## After PR is Merged
+
+Once your PR is merged:
+
+1. Sync your local main branch:
+
+```bash
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main
+```
+
+2. Delete the feature branch:
+
+```bash
+git branch -d "add-${skill_name}-skill"
+git push origin --delete "add-${skill_name}-skill"
+```
+
+## Troubleshooting
+
+**"gh: command not found"**
+
+- Install GitHub CLI: https://cli.github.com/
+- Authenticate: `gh auth login`
+
+**"Permission denied (publickey)"**
+
+- Check SSH keys: `gh auth status`
+- Set up SSH: https://docs.github.com/en/authentication
+
+**"Skill already exists"**
+
+- You're creating a modified version
+- Consider different skill name or coordinate with the skill's maintainer
+
+**PR merge conflicts**
+
+- Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`
+- Resolve conflicts
+- Force push: `git push -f origin your-branch`
+
+## Multi-Skill Contributions
+
+**Do NOT batch multiple skills in one PR.**
+
+Each skill should:
+
+- Have its own feature branch
+- Have its own PR
+- Be independently reviewable
+
+**Why?** Individual skills can be reviewed, iterated, and merged independently.
+
+## Related Skills
+
+- **writing-skills** - REQUIRED: How to create well-tested skills before sharing

package/dist/template/.opencode/skill/skill-creator/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends an agent's capabilities with specialized knowledge, workflows, or tool integrations.
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
+---
+
+# Skill Creator
+
+## When to Use
+
+- When creating a new skill or updating an existing skill with specialized workflows or tool integrations.
+
+## When NOT to Use
+
+- When making routine project changes that don't require a reusable skill.
+
+
+
+## What Skills Provide
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation loaded as needed
+    └── assets/           - Files used in output (templates, icons)
+```
+
+## Requirements
+
+- `SKILL.md` should be **less than 200 lines**
+- Use `references/` for detailed documentation
+- Each script or reference file also **less than 200 lines**
+- Descriptions must be specific about WHEN to use the skill
+
+## SKILL.md Format
+
+**REQUIRED - DO NOT SKIP**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it. Use third-person.
+---
+```
+
+**Required fields:**
+
+- `name` — hyphen-case identifier matching directory name
+- `description` — activation trigger; be specific about WHEN to use
+
+**Optional fields:**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it.
+references:
+  - references/guide.md
+  - references/api.md
+license: Apache-2.0
+---
+```
+
+**INVALID - Do NOT use:**
+
+- XML-style tags (`<purpose>`, `<references>`)
+- Missing `---` delimiters
+- Frontmatter that doesn't start at line 1
+
+## Bundled Resources
+
+### Scripts (`scripts/`)
+
+- When the same code is being rewritten repeatedly
+- When deterministic reliability is needed
+- Prefer Node.js or Python over Bash (Windows support)
+
+### References (`references/`)
+
+- Documentation that agent should reference while working
+- Database schemas, API docs, domain knowledge
+- If files are large (>10k words), include grep patterns in SKILL.md
+
+### Assets (`assets/`)
+
+- Files used in the final output (not loaded into context)
+- Templates, images, icons, boilerplate code
+
+## Progressive Disclosure
+
+Skills use three-level loading:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by agent (Unlimited)
+
+## Skill Creation Process
+
+### Step 1: Understand with Examples
+
+- "What functionality should the skill support?"
+- "Can you give examples of how this would be used?"
+- "What would a user say that should trigger this skill?"
+
+### Step 2: Plan Reusable Contents
+
+For each example, identify:
+
+- What scripts would be helpful to store?
+- What references/documentation needed?
+- What assets/templates needed?
+
+### Step 3: Create the Skill
+
+```bash
+mkdir -p .opencode/skill/my-skill
+touch .opencode/skill/my-skill/SKILL.md
+```
+
+### Step 4: Edit SKILL.md
+
+Answer these questions:
+
+1. What is the purpose of the skill?
+2. When should it be used?
+3. How should the agent use it?
+
+### Step 5: Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or bundled resources
+4. Test again
+
+## Pre-Submission Checklist
+
+- [ ] **SKILL.md starts with `---`** (YAML frontmatter, line 1)
+- [ ] **`name:` field present** and matches directory name
+- [ ] **`description:` field present** with specific activation triggers
+- [ ] **Closing `---`** after frontmatter
+- [ ] **No XML-style tags**
+- [ ] **SKILL.md under 200 lines**
+- [ ] **All referenced files exist**
+
+## Recommended Sections for SKILL.md
+
+Beyond the required structure, include these sections when applicable:
+
+### `## Gotchas`
+
+Every skill should accumulate a Gotchas section over time. This is **failure-driven documentation** — each entry should trace to a specific failure encountered during real use.
+
+```markdown
+## Gotchas
+
+- **[Short description of what went wrong]** — [What the agent did wrong, why, and the fix]. Discovered [date or session reference].
+- **[Another failure]** — [Details]. Discovered [date].
+```
+
+**Rules for Gotchas:**
+
+1. Every entry must trace to an actual failure, not a hypothetical risk
+2. Include what the agent did, why it failed, and how to avoid it
+3. New entries are added when a skill causes a failure — the fix PR should include a gotcha entry
+4. Keep entries concise (1-3 sentences each)
+5. This section grows over time and is never cleared — it's the skill's scar tissue
+
+**Why this matters:** Skills without gotchas are untested skills. A skill with 5 gotchas has been battle-tested through 5 real failures and is structurally better than a pristine skill with zero. When a skill causes a failure, always ask: "Should this become a gotcha entry?"

package/dist/template/.opencode/skill/skill-installer/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-installer
+description: Use when the user asks to list, import, or install skills from OpenAI or another GitHub repository into OpenCode skill directories.
+version: 1.0.0
+tags: [workflow, automation, integration]
+dependencies: []
+---
+
+# skill-installer
+
+Import skills from GitHub into OpenCode-compatible skill directories.
+
+## When to Use
+
+- User asks to “install skill X” from `openai/skills` or another repo
+- User wants to list available curated skills before choosing
+- User wants to copy one or more external skills into local OpenCode setup
+
+## When NOT to Use
+
+- Skill already exists locally and only needs editing
+- User asked for manual adaptation (copy + rewrite), not automated install
+
+## Default Destination
+
+- Global OpenCode skill directory: `~/.config/opencode/skill`
+- Override destination with `--dest <path>`
+
+## Scripts
+
+- `scripts/list-skills.py`
+  - Lists skills from a GitHub repo path and marks already-installed skills.
+- `scripts/install-skill-from-github.py`
+  - Installs one or many skill folders from GitHub into OpenCode skill directory.
+
+## Quick Start
+
+```bash
+# List curated skills from openai/skills
+python3 .opencode/skill/skill-installer/scripts/list-skills.py
+
+# Install one curated skill into ~/.config/opencode/skill
+python3 .opencode/skill/skill-installer/scripts/install-skill-from-github.py \
+  --repo openai/skills \
+  --path skills/.curated/screenshot
+
+# Install into project-local skills directory
+python3 .opencode/skill/skill-installer/scripts/install-skill-from-github.py \
+  --repo openai/skills \
+  --path skills/.curated/gh-fix-ci \
+  --dest .opencode/skill
+```
+
+## Notes
+
+- Supports direct GitHub URLs (`--url`) and `owner/repo` (`--repo`) mode.
+- Uses authenticated API requests if `GITHUB_TOKEN` or `GH_TOKEN` is set.
+- Fails fast if destination skill directory already exists.

package/dist/template/.opencode/skill/skill-installer/scripts/github_utils.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Shared GitHub helpers for skill install scripts."""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+
+def github_request(url: str, user_agent: str) -> bytes:
+    headers = {"User-Agent": user_agent}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"token {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as resp:
+        return resp.read()
+
+
+def github_api_contents_url(repo: str, path: str, ref: str) -> str:
+    return f"https://api.github.com/repos/{repo}/contents/{path}?ref={ref}"