### Project Installation and Setup

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Initial steps to clone the repository, install dependencies, and verify the build.

```bash
# Clone your fork
git clone git@github.com:YOUR-USERNAME/opencode-skills.git
cd opencode-skills

# Install dependencies
npm install

# Build the project
npm run build

# Run type checking
npm run typecheck
```

--------------------------------

### Install Plugin

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Add the plugin to your configuration file for auto-installation.

```json
{
  "plugin": ["opencode-skills"]
}
```

--------------------------------

### Install Latest Package

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Verify the installation of the latest published package from npm.

```bash
npm install opencode-skills@latest
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Examples of valid commit messages following the project's standards.

```bash
# Simple feature
feat: add support for nested skill directories

# Bug fix with scope
fix(parser): handle empty frontmatter correctly

# Breaking change
feat!: require Node.js 20+

BREAKING CHANGE: Drops support for Node.js 18 and below
```

--------------------------------

### Create a New Skill with SKILL.md

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Define a new skill by creating a directory and a SKILL.md file with required YAML frontmatter. This example demonstrates the basic structure and metadata.

```bash
# Create skill directory structure
mkdir -p .opencode/skills/my-skill

# Create SKILL.md with required frontmatter
cat > .opencode/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: A custom skill that helps with specific tasks in my project
license: MIT
allowed-tools:
  - read
  - write
metadata:
  version: "1.0"
---

# My Custom Skill

This skill helps you accomplish specific tasks.

## Instructions

1. First, do this
2. Then, do that
3. Finally, verify the results

You can reference supporting files like `scripts/helper.py` or `references/docs.md`.
EOF
```

--------------------------------

### Install OpenCode Skills Plugin

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Add the plugin to your OpenCode configuration to enable automatic skill discovery. Pin to a specific version for stability.

```json
// opencode.json or ~/.config/opencode/opencode.json
{
  "plugin": ["opencode-skills"]
}
```

```json
{
  "plugin": ["opencode-skills@1.0.0"]
}
```

--------------------------------

### Reference Files in Skills

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Examples of relative path referencing and the resulting base directory resolution.

```markdown
Read `references/api.md` and run `scripts/deploy.sh`
```

```text
Base directory for this skill: /path/to/.opencode/skills/my-skill/
```

--------------------------------

### Check Plugin Version

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Verify the currently installed version of the plugin.

```bash
cat ~/.cache/opencode/node_modules/opencode-skills/package.json | grep version
```

--------------------------------

### Manage Plugin Version

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Utility commands to verify the installed plugin version and force a cache refresh.

```bash
# Check installed version
cat ~/.cache/opencode/node_modules/opencode-skills/package.json | grep version

# Force update to latest (clears plugin cache)
rm -rf ~/.cache/opencode
# Then restart OpenCode
```

--------------------------------

### Create a Skill Directory

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Initialize the directory structure for a new skill.

```bash
mkdir -p .opencode/skills/my-skill
```

--------------------------------

### Build Project

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Run this command to build the project during the release checklist.

```bash
npm run build
```

--------------------------------

### Migrate to Native Skills

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Commands to transition from the plugin-based implementation to native OpenCode skill support.

```bash
# 1. Remove the plugin from opencode.json
# "plugin": ["opencode-skills"]  →  remove this line

# 2. Move skills directory (native uses singular 'skill' at project root)
mv .opencode/skills skill

# 3. For global skills
mv ~/.opencode/skills ~/.config/opencode/skill

# 4. Update configuration
# Old (plugin):
# "tools": { "skills*": false, "skills_my_skill": true }

# New (native):
# "permission": { "skill": { "my-skill": "allow", "*": "deny" } }
```

--------------------------------

### Project File Structure

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Overview of the repository layout.

```text
opencode-skills/
├── index.ts           # Main plugin export
├── dist/              # Compiled output (gitignored)
├── .opencode/         # Example skills
└── README.md
```

--------------------------------

### Release Promotion Commands

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Commands to initiate a release by promoting the development branch to the main branch.

```bash
# Create promotion PR
gh pr create \
  --base main \
  --head dev \
  --title "chore: release v0.x.x - description"

# After merge, Release Please creates release PR automatically
# Merge Release Please PR → auto-publishes to npm
```

--------------------------------

### Add opencode-sessions Plugin

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Add the sessions plugin to your configuration.

```bash
# Add to opencode.json: { "plugin": ["opencode-sessions"] }
```

--------------------------------

### Verification Commands

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Individual commands for building the project and running type checks.

```bash
npm run build
```

```bash
npm run typecheck
```

--------------------------------

### Migrate Skills Directory

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Move skill directories to the new native locations.

```bash
# Native uses skill/ (singular) at project root instead of .opencode/skills/
mv .opencode/skills skill

# For global skills
mv ~/.opencode/skills ~/.config/opencode/skill
```

--------------------------------

### Promote dev to main

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Command to create a pull request promoting integrated changes from dev to main for release.

```bash
gh pr create \
  --base main \
  --head dev \
  --title "chore: release v0.x.x - brief description" \
  --body "Promotes integrated changes from dev to main:

- feat: feature description (#PR)
- fix: bug fix description (#PR)
- docs: documentation updates

[Include BREAKING CHANGE note if applicable]

After merge, Release Please will handle versioning and publishing."
```

--------------------------------

### Sync dev with main

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Commands to update the dev branch with version bumps and changes from main after a release.

```bash
git checkout dev
git pull origin dev
git merge main
git push origin dev
```

--------------------------------

### Update Permission Configuration

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Replace tool-level configuration with the new pattern-based permission structure.

```diff
// opencode.json
{
-  "tools": {
-    "skills*": false,
-    "skills_my_skill": true
-  }
+  "permission": {
+    "skill": {
+      "my-skill": "allow",
+      "*": "deny"
+    }
+  }
}
```

--------------------------------

### Define Skill Directory Structure

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Recommended layout for organizing supporting scripts, references, and assets within a skill directory.

```text
my-skill/
├── SKILL.md              # Required
├── scripts/              # Executable code
│   └── helper.py
├── references/           # Documentation to load as needed
│   └── api-docs.md
└── assets/               # Files used in output
    └── template.html
```

--------------------------------

### Clone Repository (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Clone your forked repository using either SSH or HTTPS. Navigate into the cloned directory to begin making changes.

```bash
git clone git@github.com:YOUR-USERNAME/opencode-skills.git
```

```bash
git clone https://github.com/YOUR-USERNAME/opencode-skills.git
cd opencode-skills
```

--------------------------------

### Configure Global Skill Access

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Disable all skills by default and enable specific ones in the project configuration.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "skills*": false,
    "skills_my_skill": true
  }
}
```

--------------------------------

### Typecheck Project

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Run this command to check TypeScript types during the release checklist.

```bash
npm run typecheck
```

--------------------------------

### Perform manual version bump

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Commands to manually bump the version on the main branch if automated processes fail.

```bash
# On main branch
npm version patch  # or minor, major
git push --follow-tags
```

--------------------------------

### OpenCode Skills Discovery Paths

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

The plugin scans multiple locations for skills with a specific priority order. Later paths override earlier ones if duplicate tool names are found.

```typescript
// Discovery order - later paths override earlier ones on duplicate tool names
const discoveryPaths = [
  "~/.config/opencode/skills/",      // XDG config location (or $XDG_CONFIG_HOME/opencode/skills/)
  "~/.opencode/skills/",             // Global skills (all projects)
  "$OPENCODE_CONFIG_DIR/skills/",    // Custom OpenCode config directory (if set)
  ".opencode/skills/"                // Project-local skills (highest priority)
];
```

--------------------------------

### Develop on dev branch

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Commands to create a feature branch and open a pull request for integration into the dev branch.

```bash
git checkout dev
git checkout -b feature/your-feature-name
# ... make changes ...
gh pr create --base dev --head feature/your-feature-name
```

--------------------------------

### Implement SkillsPlugin API

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Defines the plugin structure and the Skill interface for tool discovery. Requires @opencode-ai/plugin dependency.

```typescript
import type { Plugin } from "@opencode-ai/plugin"

// Plugin signature
export const SkillsPlugin: Plugin = async (ctx) => {
  // ctx.directory - Current project directory
  // ctx.client - OpenCode client for session management

  // Discovers skills from all configured paths
  // Validates against Anthropic Skills Specification v1.0
  // Returns dynamic tools with pattern skills_{{skill_name}}

  return { tool: tools }
}

// Skill interface returned by discovery
interface Skill {
  name: string           // From frontmatter (e.g., "brand-guidelines")
  fullPath: string       // Full directory path to skill
  toolName: string       // Generated tool name (e.g., "skills_brand_guidelines")
  description: string    // From frontmatter (min 20 chars)
  allowedTools?: string[] // Parsed but not enforced (agent-level restrictions)
  metadata?: Record<string, string>
  license?: string
  content: string        // Markdown body
  path: string           // Full path to SKILL.md
}
```

--------------------------------

### Invoke a Skill

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

The command format used to trigger a registered skill.

```text
skills_my_skill
```

--------------------------------

### Configure Per-Agent Skill Access

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Override global defaults to grant specific skills to individual agents.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "skills*": false
  },
  "agent": {
    "build": {
      "tools": {
        "skills_document_skills_docx": true,
        "skills_document_skills_xlsx": true
      }
    }
  }
}
```

--------------------------------

### Create Feature Branch (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Create a new branch for your feature or fix. Follow the specified naming conventions for clarity (e.g., 'feature/description', 'fix/description').

```bash
git checkout main
git checkout -b feature/your-feature-name
```

--------------------------------

### Pin Plugin Version

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Specify a version for the plugin in your configuration.

```json
{
  "plugin": ["opencode-skills@x.y.z"]
}
```

--------------------------------

### Force Plugin Update

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Remove the cache directory to force a fresh update of plugins.

```bash
rm -rf ~/.cache/opencode
```

--------------------------------

### Push Changes to Fork (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Push your local feature branch to your forked repository on GitHub.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### SkillsPlugin Interface

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

The core plugin function that discovers skills from the project directory and returns dynamic tool definitions.

```APIDOC
## SkillsPlugin

### Description
An async function that discovers skills from configured paths, validates them against the Anthropic Skills Specification v1.0, and returns dynamic tools.

### Method
Async Function

### Response
- **tool** (Object) - A collection of dynamic tools with the pattern `skills_{{skill_name}}`.

### Skill Interface
- **name** (string) - Skill name from frontmatter.
- **fullPath** (string) - Full directory path to the skill.
- **toolName** (string) - Generated tool name.
- **description** (string) - Skill description (min 20 chars).
- **allowedTools** (string[]) - Optional agent-level tool restrictions.
- **metadata** (Record<string, string>) - Optional metadata.
- **license** (string) - Optional license information.
- **content** (string) - Markdown body of the skill.
- **path** (string) - Full path to SKILL.md.
```

--------------------------------

### Conventional Commit Format

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

The standard structure for commit messages in the project.

```text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

--------------------------------

### Define SKILL.md Frontmatter

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

The required YAML frontmatter and Markdown structure for a skill definition file.

```markdown
---
name: my-skill
description: A custom skill that helps with specific tasks in my project
license: MIT
---

# My Custom Skill

This skill helps you accomplish specific tasks.

## Instructions

1. First, do this
2. Then, do that
3. Finally, verify the results

You can reference supporting files like `scripts/helper.py` or `references/docs.md`.
```

```markdown
---
name: skill-name # Must match directory name
description: What this skill does and when to use it (min 20 chars)
license: MIT # Optional
allowed-tools: # Optional (parsed but not enforced)
  - read
  - write
metadata: # Optional key-value pairs
  version: "1.0"
---

# Skill Content

Your skill instructions in Markdown format.
```

--------------------------------

### Remove Plugin from Configuration

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

Remove the plugin entry from your opencode.json file.

```diff
// opencode.json
{
-  "plugin": ["opencode-skills"]
}
```

--------------------------------

### Control Skill Access in OpenCode

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Disable all skills by default and enable specific ones per project or per agent using the 'tools' configuration in opencode.json.

```json
// opencode.json - Project level configuration
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "skills*": false,
    "skills_my_skill": true
  }
}
```

```json
// Per-agent access control
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "skills*": false
  },
  "agent": {
    "build": {
      "tools": {
        "skills_document_skills_docx": true,
        "skills_document_skills_xlsx": true
      }
    }
  }
}
```

--------------------------------

### OpenCode Skills Tool Naming Convention

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Tool names are automatically generated from the skill directory path and its frontmatter name, using underscores.

```typescript
// Directory → Frontmatter Name → Tool Name
"brand-guidelines/"       → "brand-guidelines" → "skills_brand_guidelines"
"tools/analyzer/"         → "analyzer"         → "skills_tools_analyzer"
"document-skills/docx/"   → "docx"             → "skills_document_skills_docx"
```

--------------------------------

### Force Plugin Update

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

To force an update of the opencode-skills plugin, remove the cache directory and restart OpenCode. This ensures the latest version is fetched.

```bash
rm -rf ~/.cache/opencode
then restart
```

--------------------------------

### Maintainer Development Workflow

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Commands for managing feature branches, committing changes, and integrating code into the development branch.

```bash
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name
```

```bash
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
```

```bash
gh pr create --base dev --head feature/your-feature-name
```

```bash
npm run build
npm run typecheck
# Test in local OpenCode project
```

--------------------------------

### Add Upstream Remote (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Add the original repository as an 'upstream' remote. This allows you to fetch changes from the main project to keep your fork updated.

```bash
git remote add upstream https://github.com/malhashemi/opencode-skills.git
```

--------------------------------

### Update Local Branch (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Fetch the latest changes from the upstream repository and rebase your current branch onto the main branch to integrate updates.

```bash
git fetch upstream
git rebase upstream/main
```

--------------------------------

### SkillsPlugin API Definition

Source: https://github.com/malhashemi/opencode-skills/blob/main/README.md

The SkillsPlugin is exported as a single function that registers skills as dynamic tools. Refer to the types definition for full interface details.

```typescript
export const SkillsPlugin: Plugin
```

--------------------------------

### Commit Changes with Conventional Commits (Git)

Source: https://github.com/malhashemi/opencode-skills/blob/main/CONTRIBUTING.md

Use Conventional Commits for commit messages to standardize commit history. This includes a type (e.g., 'feat', 'fix', 'docs') and a description. Breaking changes are indicated with an exclamation mark.

```bash
git commit -m "feat: add new skill discovery feature"
```

```bash
git commit -m "fix: correct path resolution bug"
```

```bash
git commit -m "docs: update installation instructions"
```

```bash
git commit -m "feat!: change skill loading API

BREAKING CHANGE: Skills now require a version field in frontmatter"
```

--------------------------------

### Hotfix to Main Branch

Source: https://github.com/malhashemi/opencode-skills/blob/main/RELEASE.md

Use this procedure for critical fixes that must bypass the development branch. Ensure to backport the fix to the development branch afterward.

```bash
git checkout main
git checkout -b hotfix/critical-fix
# ... make fix ...
gh pr create --base main --head hotfix/critical-fix
```

```bash
git checkout dev
git cherry-pick <hotfix-commit-sha>
git push origin dev
```

--------------------------------

### Skill Frontmatter Validation

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Schema definition for validating skill frontmatter using Zod.

```APIDOC
## Skill Frontmatter Validation

### Description
Skills must contain valid YAML frontmatter validated against the following schema.

### Schema Fields
- **name** (string) - Required. Must be lowercase alphanumeric with hyphens.
- **description** (string) - Required. Must be at least 20 characters.
- **license** (string) - Optional.
- **allowed-tools** (string[]) - Optional.
- **metadata** (Record<string, string>) - Optional.
```

--------------------------------

### Subagent Skill Access Control

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

For custom subagents, control access to skills via YAML frontmatter in the agent definition.

```yaml
mode: subagent
description: Content creator agent
tools:
  skills_brand_guidelines: true
  skills_writing_style: true
```

--------------------------------

### Validate Skill Frontmatter

Source: https://context7.com/malhashemi/opencode-skills/llms.txt

Uses Zod to enforce the Anthropic skills specification on YAML frontmatter. Ensures required fields like name and description meet length and format constraints.

```typescript
import { z } from "zod"

const SkillFrontmatterSchema = z.object({
  name: z
    .string()
    .regex(/^[a-z0-9-]+$/, "Name must be lowercase alphanumeric with hyphens")
    .min(1, "Name cannot be empty"),
  description: z.string().min(20, "Description must be at least 20 characters"),
  license: z.string().optional(),
  "allowed-tools": z.array(z.string()).optional(),
  metadata: z.record(z.string()).optional(),
})

// Valid frontmatter example
const validFrontmatter = {
  name: "my-skill",
  description: "A skill that helps with specific development tasks",
  license: "MIT",
  "allowed-tools": ["read", "write", "bash"],
  metadata: {
    version: "1.0",
    author: "developer"
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.