Skip to content

urmzd/dotfiles / dot_agents/skills/extend-oss-skills-to-claude

extend-oss-skills-to-claude

Verified

Extend standard agentskills.io skills with Claude Code-specific features. Invocation control, subagent execution, dynamic context injection, string substitutions, model/effort overrides, and deployment scoping. Use when adapting a portable skill for Claude Code, adding Claude-specific frontmatter, setting up subagent delegation, or configuring skill permissions.

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.

FieldTypeDefaultPurpose
argument-hintstringnoneAutocomplete hint: [issue-number], [filename] [format]
disable-model-invocationboolfalsetrue = only the user can trigger via /name. Removes from agent context entirely.
user-invocablebooltruefalse = hidden from / menu. Agent-only background knowledge.
modelstringsessionOverride model when skill is active.
effortstringsessionOverride reasoning effort: low, medium, high, max.
contextstringnonefork = run in isolated subagent context.
agentstringgeneral-purposeSubagent type when context: fork. Built-in: Explore, Plan, general-purpose. Custom: any .claude/agents/ definition.
hooksobjectnoneLifecycle hooks scoped to this skill. See hooks docs.

Differences from Standard

AspectStandardClaude Code
nameRequiredOptional (falls back to directory name)
descriptionRequiredRecommended (falls back to first paragraph)
allowed-toolsSpace-delimitedComma-delimited
Extra fieldsIgnoredExecution 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
ConfigUser triggersAgent triggersIn agent context
defaultsYesYesDescription only
disable-model-invocation: trueYesNoNot loaded
user-invocable: falseNoYesDescription 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:

VariableDescription
$ARGUMENTSAll arguments passed after /skill-name
$ARGUMENTS[N] or $NPositional 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: <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

AgentUse case
ExploreRead-only codebase exploration, research
PlanPlanning and analysis without modifications
general-purposeFull tool access (default)
Custom (.claude/agents/)Specialized agents with preloaded skills

Deployment Scoping

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

ScopePathApplies to
EnterpriseManaged settingsAll org users
Personal~/.claude/skills/<name>/SKILL.mdAll your projects
Project.claude/skills/<name>/SKILL.mdThis project only
Plugin<plugin>/skills/<name>/SKILL.mdWhere 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: <opus-model-id>
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

MistakeFix
Using context: fork for reference/guideline contentFork needs a concrete task. Use inline for guidelines
Forgetting disable-model-invocation on side-effect skillsAlways set for deploy, commit, send, publish
Hardcoding script pathsUse ${CLAUDE_SKILL_DIR}/scripts/
Space-delimited allowed-toolsClaude Code uses commas
Setting user-invocable: false expecting it blocks Skill toolUse disable-model-invocation: true to block programmatic invocation
Forking without explicit instructionsSubagent gets guidelines but no task. Returns nothing useful
Overusing model/effort overridesSession defaults work for most skills
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall