# Skill Authoring Lifecycle

> Scaffold and formally review a new Agent Skill in this marketplace repo. Covers valid SKILL.md generation, directory layout, registry entries, and spec auditing. Use when adding a skill, validating frontmatter, or checking marketplace readiness before a PR.

- **Type:** Skill
- **Install:** `agentstack add skill-arenukvern-skill-steward-skill-authoring-lifecycle`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Arenukvern](https://agentstack.voostack.com/s/arenukvern)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Arenukvern](https://github.com/Arenukvern)
- **Source:** https://github.com/Arenukvern/skill_steward/tree/main/skills/skill-authoring-lifecycle
- **Website:** https://docs.page/arenukvern/skill_steward

## Install

```sh
agentstack add skill-arenukvern-skill-steward-skill-authoring-lifecycle
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](../../docs/decisions/0016-skill-cohesion-and-lifecycle-boundaries.mdx)).
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](../../docs/STANDARDS.mdx)): `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

```yaml
---
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 `

### 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

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

## Sources

See [references/sources.md](references/sources.md). When researching, follow `skill-source-citations`.

## Source & license

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

- **Author:** [Arenukvern](https://github.com/Arenukvern)
- **Source:** [Arenukvern/skill_steward](https://github.com/Arenukvern/skill_steward)
- **License:** MIT
- **Homepage:** https://docs.page/arenukvern/skill_steward

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-arenukvern-skill-steward-skill-authoring-lifecycle
- Seller: https://agentstack.voostack.com/s/arenukvern
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.