Skill Authoring Lifecycle

Skill authoring lifecycle

Add, review, and validate an installable skill package under skills/ in the Skill Steward marketplace.

When to use

• User wants a new skill in this repo
• "Review this skill" or "Is this SKILL.md valid?"
• Bootstrapping SKILL.md for npx skills compatibility
• PR touches skills/*/SKILL.md

Phase 1: Creation Workflow

1. Verify intent — Does the intent overlap with an existing skill? Merge into an existing skill if they serve the same high-level goal or are two halves of the same lifecycle (ADR 0016).
2. Collect examples — Write 2–3 concrete user prompts that should trigger the skill and 1 prompt that should not. Skip only when the request already supplies clear usage patterns.
3. Plan resources — Decide whether the skill needs instructions only, scripts/ for repeated or fragile operations, references/ for detailed knowledge, or assets/ for templates/static files.
4. Choose a name — kebab-case, 1–64 chars, matches Agent Skills rules (see docs/STANDARDS.mdx).
5. Create directory — skills/{name}/ (directory name must equal name in frontmatter).
6. Copy template — from templates/skill/SKILL.md; replace placeholders.
7. Write description — one concise block covering what and when (trigger phrases users say). Activation-critical routing belongs here, not only in a body "When to use" section.
8. Cite sources — create references/sources.md from templates/skill/references/sources.md; add rows for every spec/repo/paper used.
9. Write body — numbered steps, examples, output format; keep under 500 lines.
10. Evals — T1 behavior-critical skills (see STANDARDS): references/evals.md + ≥2 evals/cases/*.yaml. Others: optional evals.md.
11. Optional metadata — add agents/openai.yaml only when Codex app UI metadata, invocation policy, or tool dependencies are useful.
12. Optional resources — create only the needed scripts/, references/, and assets/ directories; delete placeholder resources.
13. Register skill:

• Add skill id to skills.sh.json using the current repo schema.
• Add row to root README.md skill table.

14. Forward-test tricky skills — For broad or fragile workflows, use a fresh subagent/thread with a natural user prompt and raw artifacts. Do not leak the intended answer, suspected bug, or planned fix into the validation prompt.

Frontmatter template

---
name: {same-as-directory}
description: {capability + trigger phrases, 20-1024 chars}
license: MIT
type: governance
metadata:
  author: skill-steward
  version: "1.0.0"
  category: {marketplace|multi-agent|...}
---

Phase 2: Review & Audit Checklist

Review a skill package before merge or publish to skills.sh.

Skill Cohesion

• Complete lifecycle: The skill covers a complete journey (e.g., creating + validating) rather than forcing an agent to switch tools mid-task.
• Mechanics included: Abstract rules or culture guidelines are bundled alongside the mechanical tools that enforce them.

Structure

• Directory name is kebab-case and matches name in frontmatter
• File is exactly SKILL.md (case-sensitive)
• No README.md inside the skill folder (use references/)

Frontmatter

• name: 1–64 chars, [a-z0-9-], no leading/trailing -, no --
• description: 1–1024 chars, states capability and when to activate
• license set if not repo MIT
• metadata.version and metadata.author
• compatibility if skill needs git, network, docker, or a specific product
• agents/openai.yaml present only when Codex-specific UI/policy/dependency metadata is useful

Body

• Clear numbered workflow
• Under ~500 lines (or split to references/)
• Relative file links one level deep
• references/sources.md with URLs for external claims
• Install command documented: npx skills add arenukvern/skill_steward --skill <name>

Distribution Readiness

• Skill can run from a copied directory without relying on repo-relative paths outside its own package unless those paths are explicitly documented
• Agent-specific assumptions are isolated to optional metadata or references, not baked into the core workflow
• If the skill may be bundled inside a product plugin, the product repo owns the copy/init script and host manifests; the skill remains canonical in skills/{name}/
• Marketplace or plugin-readiness language distinguishes skills-only install, local copy/init scripts, host manifests, and public marketplace submission proof
• Vendor-specific claims cite current Codex, Cursor, Claude, Zed, or npx skills sources in references/sources.md

Scripts (if present)

• Shebang present (bash or node)
• set -euo pipefail for bash
• stderr for logs, stdout for machine-readable output
• Representative scripts were actually run, or skipped with a recorded reason

Registry (this repo)

• Skill id in skills.sh.json
• Row in root README.md table
• pnpm run validate passes (no sources.md warning)
• T1 behavior-critical: evals/cases/*.yaml + pnpm run eval

Phase 3: Deprecation & Renaming (Changesets)

We do not keep permanent "tombstone" skills, as they clutter the repository. Instead, we treat skill renames and merges as breaking API changes and communicate them using standard ecosystem tooling (Changesets).

When renaming or merging a skill:

1. Safely rm -rf the old skill directory.
2. Remove the old skill from skills.sh.json and README.md.
3. Generate a changeset (pnpm changeset) documenting the deletion, or manually create a .changeset/skill-consolidation.md file. Explain clearly why it was removed and which skill replaces it.
4. Agents and users reading the changelog will automatically see the redirection.

Output format for Reviews

Report as:

## Summary
{pass | needs changes}

## Errors (blocking)
...
## Warnings
...

Install

npx skills add arenukvern/skill_steward --skill skill-authoring-lifecycle

Sources

See references/sources.md. When researching, follow skill-source-citations.