Create Skill

Create Skill

Bootstrap a new agent skill, then symlink it into .claude/skills/ so Claude Code can discover it. Default to splitting bulk content into references/ and scripts/ so SKILL.md stays lean.

Arguments

• skill-name (required): kebab-case name (e.g., my-skill). Stop if missing or invalid.
• --global (optional): install under ~ instead of the current repo.

Resolved Paths

| Mode | Skill source | Claude Code symlink | | --------------- | -------------------------- | ------------------------- | | local (default) | .agents/skills// | .claude/skills/ | | --global | ~/.agents/skills// | ~/.claude/skills/ |

For local mode, ` is the chosen project directory. It may be the repository root or a nested project/workspace directory under a larger repo; a local .agents/skills/` below the repo root is valid when that is the intended project scope.

The symlink target is always the relative path ../../.agents/skills/ so it resolves correctly in both scopes.

Skill Layout

/
├── SKILL.md       # Required: frontmatter + lean workflow (aim for 100 lines: include a table of contents at the top.
- Files >10k words: document grep patterns in `SKILL.md` so the agent can locate sections without reading the whole file.
- **No duplication** — each fact lives in `SKILL.md` *or* a reference, never both.
- For every reference, write one line in `SKILL.md` that says *when* to read it.

### Reference organization patterns

**Pattern A — High-level guide + topical references**

SKILL.md references/ ├── forms.md ├── api.md └── examples.md

`SKILL.md` teaches the happy path; references hold deep-dive material.

**Pattern B — Domain or variant split**

SKILL.md # workflow + selection logic references/ ├── aws.md ├── gcp.md └── azure.md

The agent reads only the variant the user picked — irrelevant providers never enter context.

**Pattern C — Conditional details**

Inline the basic case in `SKILL.md`, link advanced files for edge cases (`tracked-changes.md`, `ooxml.md`, etc.).

### Do NOT add to a skill

- `README.md`, `INSTALLATION.md`, `CHANGELOG.md`, `QUICK_REFERENCE.md` — extraneous.
- Notes about how the skill was authored, test logs, scratch files.
- Anything the agent will not use at runtime.

## Workflow

### 1. Fetch Agent Skills Docs

Always fetch the latest spec before authoring frontmatter or content:

- https://agentskills.io

Use `WebFetch` to confirm the current frontmatter schema, naming rules, and progressive-disclosure conventions. Do not guess — the spec evolves.

### 2. Validate

- Reject names that are not kebab-case or collide with an existing skill at the resolved path.
- Accept local scopes nested under a larger repo; do not force the skill into the repo root when the task targets a nested project directory.
- Stop if `/.agents/skills//` or `/.claude/skills/` already exists.

### 3. Plan the Layout

Before writing anything, decide what belongs where:

- Will the workflow invoke helper code? → `scripts/.{sh,py,ts}`
- Schemas, long examples, variant guides, domain knowledge? → `references/.md`
- Templates or files the skill writes into the user's output? → `assets/`
- None of the above? → ship just `SKILL.md`.

Sketch the directory tree first, then create only the subdirectories the layout actually needs.

### 4. Create the Skill

```bash
mkdir -p "/.agents/skills//agents"
# Add only the subdirectories the layout calls for:
# mkdir -p "/.agents/skills//scripts"
# mkdir -p "/.agents/skills//references"

Write /.agents/skills//SKILL.md with:

• Frontmatter sorted alphabetically, with description last. The description is the only field seen at discovery time — front-load trigger phrases there, not in the body.
• A short # Title.
• A one-line summary of what the skill does.
• disable-model-invocation and user-invocable fields set for Claude behavior. Omit only when intentionally relying on Claude defaults: disable-model-invocation: false, user-invocable: true.
• ## Arguments (if any) and ## Workflow sections in imperative form with concrete steps.
• Explicit links to every references/ file the workflow may need, each with a one-line note describing when to read it.
• CLI signatures for any bundled scripts so the agent can call them without reading them.

Aim for SKILL.md under 500 lines. If a section grows past ~50 lines and is not core workflow, move it to references/ and link it.

Write /.agents/skills//agents/openai.yaml with:

policy:
  allow_implicit_invocation: true

Set allow_implicit_invocation to the inverse of SKILL.md disable-model-invocation. If later adding Codex UI metadata or MCP/tool dependencies, merge them into the same file and keep the policy.

5. Create the Claude Code Symlink

Always create a relative symlink so Claude Code picks the skill up from its own discovery path:

mkdir -p "/.claude/skills"
ln -s "../../.agents/skills/" "/.claude/skills/"

6. Verify

• test -f "/.agents/skills//SKILL.md"
• test -f "/.agents/skills//agents/openai.yaml"
• readlink "/.claude/skills/" resolves to the source directory.
• Print both absolute paths to the user.

Notes

• Frontmatter rule: sort fields alphabetically, but always place description last.
• Codex parses SKILL.md frontmatter as YAML before loading a skill. Avoid unquoted colon-space tokens in scalar values

such as Triggers: "foo" inside description; either omit the label or quote the whole value.

• "When to use" information belongs in description (discovery-time), not in the body (activation-time only).
• Use imperative / infinitive form throughout SKILL.md.
• All paths inside SKILL.md (e.g., references/placeholder.md, scripts/example.sh) are relative to the skill directory.
• Every new skill must include agents/openai.yaml with policy.allow_implicit_invocation derived from SKILL.md, never the other way around.
• Bash scripts inside the skill must be compatible with Bash 3.2 (/bin/bash), since Codex uses the built-in Bash by default.
• Do not commit the new skill — leave that to the user.

Source & license

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

• Author: PaulRBerg
• Source: PaulRBerg/agent-skills
• License: MIT

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