Extend Oss Skills To Claude

Extend OSS Skills to Claude Code

> Prerequisite: read create-oss-skill first. That skill owns the base agentskills.io format and shared reference material (description optimization, eval workflow). This skill contains only the Claude Code-specific deltas (invocation control, subagent execution, dynamic context injection, model/effort overrides, deployment scoping).

Take a standard agentskills.io skill and layer on Claude Code execution features. The base spec defines a portable file format; Claude Code turns it into an execution framework.

What the Standard Covers

The open standard defines: name (required), description (required), license, compatibility, metadata, allowed-tools (space-delimited). These fields work across all compatible agents (Cursor, Gemini CLI, OpenCode, Goose, etc.). Start with create-oss-skill for the base format.

Claude Code Extended Frontmatter

These fields are Claude Code-specific. Other agents ignore them.

| Field | Type | Default | Purpose | |-------|------|---------|---------| | argument-hint | string | none | Autocomplete hint: [issue-number], [filename] [format] | | disable-model-invocation | bool | false | true = only the user can trigger via /name. Removes from agent context entirely. | | user-invocable | bool | true | false = hidden from / menu. Agent-only background knowledge. | | model | string | session | Override model when skill is active. | | effort | string | session | Override reasoning effort: low, medium, high, max. | | context | string | none | fork = run in isolated subagent context. | | agent | string | general-purpose | Subagent type when context: fork. Built-in: Explore, Plan, general-purpose. Custom: any .claude/agents/ definition. | | hooks | object | none | Lifecycle hooks scoped to this skill. See hooks docs. |

Differences from Standard

| Aspect | Standard | Claude Code | |--------|----------|-------------| | name | Required | Optional (falls back to directory name) | | description | Required | Recommended (falls back to first paragraph) | | allowed-tools | Space-delimited | Comma-delimited | | Extra fields | Ignored | Execution control, subagent delegation |

Keep name and description required in practice; portability matters.

Invocation Control

Two fields control who can trigger a skill:

# User-only: deploy, commit, send-message. Side effects you control
disable-model-invocation: true

# Agent-only: background context the user shouldn't invoke directly
user-invocable: false

| Config | User triggers | Agent triggers | In agent context | |--------|--------------|----------------|------------------| | defaults | Yes | Yes | Description only | | disable-model-invocation: true | Yes | No | Not loaded | | user-invocable: false | No | Yes | Description only |

Use disable-model-invocation: true for anything with side effects. Use user-invocable: false for domain knowledge the agent should know but isn't an action.

String Substitutions

Available in skill body content:

| Variable | Description | |----------|-------------| | $ARGUMENTS | All arguments passed after /skill-name | | $ARGUMENTS[N] or $N | Positional argument (0-based) | | ${CLAUDE_SESSION_ID} | Current session ID | | ${CLAUDE_SKILL_DIR} | Directory containing this SKILL.md |

If $ARGUMENTS is absent from content, arguments are appended as ARGUMENTS: .

---
name: fix-issue
disable-model-invocation: true
argument-hint: "[issue-number]"
---
Fix GitHub issue $ARGUMENTS following our coding standards.

Multi-argument example:

---
name: migrate-component
argument-hint: "[component] [from] [to]"
---
Migrate the $0 component from $1 to $2.

Dynamic Context Injection

The ` !command ` syntax runs shell commands before the skill content reaches the agent. Output replaces the placeholder inline.

---
name: pr-summary
context: fork
agent: Explore
---
## Context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`
- PR comments: !`gh pr view --comments`

Summarize this pull request.

This is preprocessing. The agent sees rendered output, not the commands. Use for fetching live data (git state, API responses, environment info).

Subagent Execution

context: fork runs the skill in an isolated context without conversation history. The skill body becomes the subagent's task prompt.

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

When to fork:

• Task is self-contained and doesn't need conversation history
• You want isolation (read-only exploration, parallel research)
• The skill has explicit step-by-step instructions (not just guidelines)

When NOT to fork:

• Skill is reference content (conventions, patterns, style guides)
• Skill needs to interact with the user's ongoing conversation
• Instructions are guidelines without a concrete task

Agent Types

| Agent | Use case | |-------|----------| | Explore | Read-only codebase exploration, research | | Plan | Planning and analysis without modifications | | general-purpose | Full tool access (default) | | Custom (.claude/agents/) | Specialized agents with preloaded skills |

Deployment Scoping

Claude Code adds a hierarchy the standard doesn't define:

| Scope | Path | Applies to | |-------|------|------------| | Enterprise | Managed settings | All org users | | Personal | ~/.claude/skills//SKILL.md | All your projects | | Project | .claude/skills//SKILL.md | This project only | | Plugin | /skills//SKILL.md | Where plugin enabled |

Priority: enterprise > personal > project. Plugin skills use plugin-name:skill-name namespace (no conflicts).

Monorepo support: skills in nested .claude/skills/ directories auto-discovered when working in subdirectories.

Tool Restrictions and Permissions

Claude Code extends allowed-tools beyond the standard:

# Standard (space-delimited, informational)
allowed-tools: Read Grep Glob

# Claude Code (comma-delimited, enforced as permission grants)
allowed-tools: Read, Grep, Glob, Bash(git *)

Claude Code also supports pattern-based tool permissions:

• Bash(git *) allow git commands
• Bash(npm test) allow specific command
• Read, Grep, Glob read-only mode

Users can restrict skill access via permission rules:

Skill(deploy *)    # deny deploy skill
Skill(commit)      # allow commit skill

Model and Effort Overrides

Override per-skill when the default isn't appropriate:

---
name: complex-analysis
model: 
effort: max
context: fork
---

Use sparingly. Most skills work fine with session defaults.

Lifecycle Hooks

Scope hooks to skill execution for pre/post processing:

---
name: deploy
hooks:
  pre: scripts/pre-deploy-check.sh
  post: scripts/notify-slack.sh
---

See hooks documentation for full configuration.

Extended Thinking

Include the word "ultrathink" in skill content to enable extended thinking mode for the skill's execution.

Portability Checklist

When extending a standard skill for Claude Code:

1. Keep standard fields (name, description, license, compatibility) intact and valid
2. Add Claude Code fields alongside. Other agents ignore unknown frontmatter
3. Switch allowed-tools delimiter from spaces to commas
4. Test the skill still works as plain markdown instructions (graceful degradation)
5. Document Claude-specific features in a comment or separate section so contributors understand
6. Use ${CLAUDE_SKILL_DIR} instead of hardcoded paths for script references

Template

---
name: 
description: >
  . Use when .
# --- Standard fields above, Claude Code extensions below ---
argument-hint: "[arg1] [arg2]"
disable-model-invocation: true
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
effort: high
metadata:
  author: 
  version: "1.0"
---

# 

## Context
- Current branch: !`git branch --show-current`
- Recent changes: !`git log --oneline -5`

## Instructions

## Gotchas

Common Mistakes

| Mistake | Fix | |---------|-----| | Using context: fork for reference/guideline content | Fork needs a concrete task. Use inline for guidelines | | Forgetting disable-model-invocation on side-effect skills | Always set for deploy, commit, send, publish | | Hardcoding script paths | Use ${CLAUDE_SKILL_DIR}/scripts/ | | Space-delimited allowed-tools | Claude Code uses commas | | Setting user-invocable: false expecting it blocks Skill tool | Use disable-model-invocation: true to block programmatic invocation | | Forking without explicit instructions | Subagent gets guidelines but no task. Returns nothing useful | | Overusing model/effort overrides | Session defaults work for most skills |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: urmzd
• Source: urmzd/dotfiles
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.