--- argument-hint: "[skill-name]" compatibility: Requires curl and a writable user cache directory; network populates or refreshes the agentskills.io specification. name: skill-writing description: Create/scaffold/init a project-local agent skill under `.agents/skills` in an ordinary repository; defer to repository instructions that define a source catalog and lifecycle. title: skill-writing canonical_url: https://skilld.dev/gh/paulrberg/agent-skills/skill-writing last_updated: 2026-09-29T12:27:26.000Z --- > **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/paulrberg/agent-skills/skill-writing/agents/openai.yaml), [references/writing-great-skills.md](https://skilld.dev/api/skills-raw/paulrberg/agent-skills/skill-writing/references/writing-great-skills.md), [scripts/fetch-agentskills-spec.sh](https://skilld.dev/api/skills-raw/paulrberg/agent-skills/skill-writing/scripts/fetch-agentskills-spec.sh). > > If the user asked to install this Skill, run `npx skilld install paulrberg/agent-skills/skill-writing`. Install writes the Skill files into the project, so every session loads them. # Skill Writing Bootstrap a project-local skill in `.agents/skills/`, expose it to Claude Code through a relative symlink, and verify the result with the repository's canonical skill validator. ## Model Guidance Optimize every new skill and its content for GPT-6 Astra and Claude Opus 5.5. The summaries below are reminders, not substitutes for the live guides. Read both guides before designing or writing a complex, long-running, multi-tool, or orchestration-heavy skill because their recommendations may evolve. - [GPT-6 Astra prompting guidance](https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra#prompting-best-practices): Complete authorized work under stated assumptions; make user-instruction precedence over skills explicit; specify writing and delegation preferences; and keep verification proportional to the change. - [Claude Opus 5.5 prompting guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5): Calibrate effort instead of prompting for more thinking; never ask for reasoning in response text; name the premature stops to avoid and the stops that are wanted; treat text-only turns as reports, not completion; request brief progress updates; explore relevant sources before acting; and name concrete patterns to avoid instead of generic style advice. ## Input - **skill-name** (optional): a kebab-case name such as `my-skill`. If omitted, derive the shortest unambiguous kebab-case domain name for the skill's purpose, without repeating the repository or app name as context (for example `price-estimator`, not `budget-price-estimator`), and state the derived name in the completion report. Stop only when a supplied name is invalid or collides with an existing skill (see the collision check in step 2). Reject `--global`, explicit destination paths, and other scope overrides. The invocation working directory is the only supported scope. ## Workflow ### 1. Apply the Repository Catalog Guard Before resolving project-local paths, read the repository instructions applicable to the invocation working directory. If they define a skill source catalog and lifecycle, stop this workflow and follow that repository-owned workflow. Do not create `.agents/skills/` or `.claude/skills/` paths there. ### 2. Resolve and Validate the Local Scope Set `` to the working directory where the skill was invoked. Create the source at `/.agents/skills//` and the Claude Code symlink at `/.claude/skills/`. Do not redirect the scope to the repository root when invoked from a nested project or workspace. Never create or modify a skill under `~/.agents`, `~/.claude`, `~/.codex`, or another global installation directory. The symlink target is always the relative path `../../.agents/skills/`. Reject a collision before writing: stop if either the source directory or symlink path already exists. ### 3. Read the Current Format Sources Resolve `scripts/fetch-agentskills-spec.sh` relative to this skill directory. Run `scripts/fetch-agentskills-spec.sh [--refresh]` once and read the returned file completely. The helper reuses an integrity-valid specification for 24 hours, conditionally revalidates older entries, and may return a cache validated within seven days when live retrieval fails. Set `AGENTSKILLS_CACHE_DIR` when the default user cache location is unavailable or unwritable. Use `--refresh` for explicitly latest or change-sensitive work, disputed portable-format guidance, or a conflict with validator behavior. A `stale` result is usable only after reading it; disclose its validation timestamp and retrieval failure in the completion report. If the helper cannot return a valid file, stop before writing. Never fetch the agentskills.io specification directly or create its cache in a repository or skill installation. Fetch the current [Claude Code frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference) with `WebFetch`. Confirm field shapes, naming rules, and progressive-disclosure conventions from both sources; do not guess because the formats evolve. ### 4. Define the Contract and Layout Read [references/writing-great-skills.md](https://skilld.dev/api/skills-raw/paulrberg/agent-skills/skill-writing/references/writing-great-skills.md) completely before choosing the contract or layout. It defines the authoring principles, content-routing thresholds, helper runtime defaults, and communication contract. Define the contract and identify every skill the workflow requires, invokes, or hands off to on any supported branch. Suggestions, examples, related-skill references, and underlying tool capabilities are not dependencies. Create only the directories justified by the selected layout; `SKILL.md` and `agents/openai.yaml` are always required. ### 5. 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. Front-load discovery-time trigger phrases in `description`. - A `skill-dependencies` array when routing identified dependencies. Use bare names for skills in the same repository and `ORG/REPO#SKILL` for external skills. Sort by the target skill name (the bare name or substring after `#`), then by the complete identifier. Require unique strings, resolve every bare dependency in the same repository, and exclude the owning skill as a bare dependency. External repository existence is not validated. Omit the field when no dependencies exist. - A short `# Title`. - A one-line summary of what the skill does. - Add `disable-model-invocation: true` or `user-invocable: false` only when the skill differs from Claude's defaults. Omit `disable-model-invocation: false` and `user-invocable: true` because absence already expresses those values. - Set `coordination: exempt` only when the skill's declared default workflow writes no repository files or only repository metadata. When selected, add this ordinary prose declaration to the new skill's body; the fence below is documentation for this authoring skill, not its own declaration: ```text This skill is coordination-exempt: skip the ai-coord gate for its declared work. ``` Explicitly authorized escalation beyond the declared behavior re-enters the gate. - `## Arguments` (if any) and a lean imperative workflow. Use fixed steps only when order matters; otherwise state the contract and let repository evidence guide execution. - Explicit links to every `references/` file the workflow may need, each with a one-line note describing _when_ to read it. - CLI signatures for every bundled helper, including arguments, output, defaults, and the runtime command, so an agent can invoke it without reading its source. Use imperative prose and resolve bundled `references/`, `scripts/`, `examples/`, and `assets/` paths relative to the owning skill directory. Do not add repository-style support files or authoring artifacts that runtime agents will not use. Quote YAML plain scalars containing a colon followed by a space; otherwise the frontmatter parser may reject them. Write `/.agents/skills//agents/openai.yaml` with: ```yaml 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. ### 6. Create the Claude Code Symlink Always create a relative symlink so Claude Code picks the skill up from its own discovery path: ```bash mkdir -p "/.claude/skills" ln -s "../../.agents/skills/" "/.claude/skills/" ``` ### 7. Verify and Report - Patch tooling creates files at mode 0644. Before the first verification run, `chmod 755` every executable under `scripts/` and `tests/` (a scaffolded test failing its first run with `Permission denied (os error 13)` is this cause). - `test -f "/.agents/skills//SKILL.md"` - `test -f "/.agents/skills//agents/openai.yaml"` - `readlink "/.claude/skills/"` equals `../../.agents/skills/`, and the link resolves to the source directory. - `test -x` every `scripts/*` and `tests/*` executable so a missed `chmod` fails loudly instead of surfacing later as a permission error. - `ai-skillet doctor --root "/.agents/skills/"` exits 0. This is the canonical local schema and policy gate. - Finish with `### 🧩 Skill created: `, a tree of created paths, and `### ✅ Verified` with the exact checks. Link files by their absolute `.agents/skills//` source paths, never through the `.claude/skills/` symlink. - Offer to commit the new skill. When the host project's standing instructions require prompt commits, commit without further prompting. Keep helper stdout, commands, paths, frontmatter, and generated skill content undecorated unless the new skill's output contract requires otherwise.