| name | harness-skill |
| description | Create and manage skill entities in the agent-harness workspace. Use when the user wants to add a new skill, understand how skills work across providers, or generate provider skill artifacts from a canonical source. |
harness-skill
You are helping the user create or manage a skill entity in the agent-harness workspace. Skills are reusable slash commands and procedural capabilities defined once in .harness/src/ and rendered into every enabled provider's native format by npx harness apply.
Follow the steps and reference material below to complete the user's request.
What is a skill entity?
A skill entity is the canonical source for a reusable, invocable capability. Define it once in .harness/src/skills/<skill-id>/ and harness generates the matching artifacts for every enabled provider (Claude Code, OpenAI Codex, GitHub Copilot). This means one source of truth drives slash commands in all three tools.
Source structure
.harness/src/skills/<skill-id>/
├── SKILL.md # Main instructions (required)
├── reference.md # Optional supplementary docs
├── examples/ # Optional example files
└── scripts/ # Optional scripts referenced in SKILL.md
SKILL.md is the only required file. Any additional files in the directory are copied alongside it into each provider's output directory.
Workflow
npx harness add skill <skill-id>
npx harness apply
npx harness remove skill <skill-id>
After npx harness apply, provider artifacts are written to the paths described below. Commit both .harness/src/ and the generated provider files.
Provider output mapping
Claude Code
-
Output path: .claude/skills/<skill-id>/SKILL.md (plus any supporting files)
-
Invocation: /<skill-id> in a Claude Code session
-
Discovery: Claude Code scans .claude/skills/ in the project root and in every subdirectory up to the repo root (supports monorepos). Personal skills live at ~/.claude/skills/<skill-id>/.
-
How it works: The SKILL.md content becomes the prompt Claude receives when the skill is invoked. Claude also loads skill descriptions into context so it can invoke matching skills automatically unless disable-model-invocation: true is set.
-
Frontmatter fields supported:
| Field | Required | Notes |
|---|
name | No | Defaults to directory name. Lowercase, hyphens only, max 64 chars. |
description | Recommended | Used by Claude to decide when to auto-invoke. |
argument-hint | No | Autocomplete hint, e.g. [filename]. |
disable-model-invocation | No | true = only user can invoke via /skill-id. |
user-invocable | No | false = hidden from / menu, Claude-only. |
allowed-tools | No | Tools permitted without per-use approval. |
model | No | Model override for this skill. |
effort | No | low, medium, high, or max. |
context | No | fork to run in an isolated subagent. |
agent | No | Subagent type when context: fork is set. |
hooks | No | Lifecycle hooks scoped to this skill. |
-
Argument substitution: Use $ARGUMENTS for all passed args, $ARGUMENTS[N] or $N for positional args, ${CLAUDE_SKILL_DIR} for the skill directory path, ${CLAUDE_SESSION_ID} for the session ID.
-
Dynamic context: !`<shell-command>` in the skill body runs the command before Claude sees the prompt; the output is injected inline.
-
Official docs: https://code.claude.com/docs/en/slash-commands
OpenAI Codex CLI
- Output path:
.codex/skills/<skill-id>/SKILL.md (plus any supporting files)
- Discovery: Codex scans both
.codex/skills/ and .agents/skills/ from $CWD up to the repo root. Personal skills live at ~/.agents/skills/ (preferred) or ~/.codex/skills/ (deprecated). Harness writes to .codex/skills/ at the project level.
- Invocation: Type
/skills or $ to mention a skill by name. Codex also selects skills implicitly based on the task description unless allow_implicit_invocation: false is set.
- How it works: Codex uses progressive disclosure — it loads only skill metadata initially and reads full instructions upon activation.
- Frontmatter fields supported:
name and description are the primary fields. An optional agents/openai.yaml sidecar in the skill directory can set policy.allow_implicit_invocation, display metadata, and tool dependencies.
- Official docs: https://developers.openai.com/codex/skills
GitHub Copilot
-
Output path: .github/skills/<skill-id>/SKILL.md (plus any supporting files)
-
Discovery: Copilot scans .github/skills/, .claude/skills/, and .agents/skills/ for project skills. Personal skills live at ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/. Works in Copilot coding agent, Copilot CLI, and agent mode in VS Code. Harness writes to .github/skills/ to avoid duplication across the scanned paths.
-
Invocation: Copilot automatically determines when to use a skill based on context. When activated, the full SKILL.md is injected into the agent's context. In VS Code, skills also appear as /<skill-name> slash commands.
-
How it works: Skills supplement custom instructions (.github/copilot-instructions.md). Use custom instructions for broad coding standards; use skills for detailed, task-specific procedures Copilot should only load when relevant.
-
Frontmatter fields supported:
| Field | Required | Notes |
|---|
name | Yes | Unique lowercase identifier matching the directory name (max 64 chars). |
description | Yes | What the skill does and when Copilot should use it (max 1024 chars). |
argument-hint | No | Hint text for slash command invocation (VS Code). |
disable-model-invocation | No | true = Copilot won't auto-load this skill (VS Code). |
user-invocable | No | false = hidden from / menu (VS Code). |
license | No | Applicable licensing terms (coding agent). |
-
Official docs: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills
Cursor
-
Output path: .cursor/skills/<skill-id>/SKILL.md (plus any supporting files)
-
Discovery: Cursor loads skills from .agents/skills/, .cursor/skills/, and ~/.cursor/skills/. For compatibility, it also scans .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/. Harness writes to .cursor/skills/ at the project level.
-
Invocation: / followed by the skill name in Agent chat, or automatic when the agent determines the skill is relevant.
-
How it works: Cursor discovers skills at startup and presents them to the agent. The agent decides when they are relevant based on context. Skills can also include scripts/, references/, and assets/ subdirectories for supporting files.
-
Frontmatter fields supported:
| Field | Required | Notes |
|---|
name | Yes | Must match the parent folder name. Lowercase letters, numbers, and hyphens only. |
description | Yes | Used by the agent to determine relevance. |
license | No | License name or reference. |
compatibility | No | Environment requirements. |
metadata | No | Arbitrary key-value mapping. |
disable-model-invocation | No | true = only included when explicitly invoked via /skill-name. |
-
Official docs: https://docs.cursor.com/agent/skills
Provider-specific differences at a glance
| Aspect | Claude Code | Codex CLI | GitHub Copilot | Cursor |
|---|
| Output root | .claude/skills/ | .codex/skills/ | .github/skills/ | .cursor/skills/ |
| Invocation | /<skill-id> | /skills or $mention | Automatic on context match | /<skill-id> or automatic |
| Auto-invoke | Yes (opt-out via frontmatter) | Yes (opt-out via openai.yaml) | Yes (opt-out via frontmatter in VS Code) | Yes (opt-out via disable-model-invocation) |
| Frontmatter richness | Extensive (11+ fields) | Minimal (name, description) | Moderate (name, description, plus VS Code fields) | Moderate (name, description, plus 4 optional fields) |
| Argument passing | $ARGUMENTS, $N placeholders | Not specified | Not applicable | Not specified |
| Subagent execution | context: fork | Not applicable | Not applicable | Not applicable |
| Supporting files | Fully supported | Supported (scripts/, references/) | Supported | Supported (scripts/, references/, assets/) |
SKILL.md format guide
A SKILL.md is a Markdown file with optional YAML frontmatter. Write it as an actionable prompt — describe what Claude (or the provider) should do when the skill is invoked.
Structure:
---
name: my-skill
description: One sentence on what this skill does and when to use it.
disable-model-invocation: true # optional: only if user-triggered only
argument-hint: "[target-file]" # optional
---
# my-skill
Brief summary of the skill's purpose.
## Steps
1. First action
2. Second action
3. ...
## Notes
Any caveats or prerequisites.
Content tips:
- Write instructions in the imperative ("Read the file", "Run the tests", "Create a PR").
- Include the
$ARGUMENTS placeholder where user input should appear.
- Keep
SKILL.md under 500 lines; move large reference material to separate files in the directory and link them from SKILL.md.
- The
description frontmatter field is the most important — it determines when providers auto-invoke the skill. Make it specific.
Minimal working example
Directory layout:
.harness/src/skills/run-tests/
└── SKILL.md
.harness/src/skills/run-tests/SKILL.md:
---
name: run-tests
description: Run the test suite for the current project and summarize failures. Use when the user asks to run tests, check test results, or debug a failing test.
---
Run the project test suite and report results.
1. Detect the test runner (check package.json scripts, Makefile, or pyproject.toml).
2. Run the tests: `$ARGUMENTS` (use this as extra flags if provided, otherwise omit).
3. Parse the output and list any failures with file name and line number.
4. Suggest a fix for the first failing test if the cause is clear.
After npx harness apply this produces:
.claude/skills/run-tests/SKILL.md — invoked as /run-tests in Claude Code.codex/skills/run-tests/SKILL.md — available via $run-tests in Codex.github/skills/run-tests/SKILL.md — auto-loaded by Copilot when tests are relevant
Harness CLI reference
npx harness add skill <skill-id>
npx harness apply
npx harness plan
npx harness remove skill <skill-id>
npx harness remove skill <skill-id> --no-delete-source
npx harness provider enable claude
npx harness provider enable codex
npx harness provider enable copilot
Official documentation
