Extend OSS Skills to Claude Code

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.

Differences from Standard

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

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:

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

---
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

Deployment Scoping

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

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: claude-opus-4-6
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: <skill-name>
description: >
  <What it does>. Use when <trigger conditions>.
# --- 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: <org>
  version: "1.0"
---

# <Skill Title>

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

## Instructions

<Step-by-step guidance using $ARGUMENTS.>

## Gotchas

<Claude Code-specific pitfalls.>

Common Mistakes