my-skill/
├── SKILL.md         # Required — instructions + metadata
├── scripts/         # Optional — executable JS, Python, or bash
├── references/      # Optional — supplementary docs, loaded on demand
└── assets/          # Optional — templates, data files

---
name: pr-summary-for-stakeholders
description: >
  Use when asked to summarize a GitHub pull request for a non-technical
  audience, product manager, or executive. Translates technical changes
  into business impact. Do not use for technical code reviews.
---

---
name: financial-report-generator
description: >
  Generates a compliant financial report in IFRS, GAAP, or OHADA format.
  Use when the user requests a financial report or a regulated compliance
  document. Do not use for exploratory analysis.
license: Apache-2.0
metadata:
  version: "1.2.0"
  changelog: "1.2.0 - OHADA (TG/CI/SN) · 1.1.0 - cache fallback · 1.0.0 - IFRS+GAAP"
  author: "Luc K. SEGBEDZI"
---

## Step 1 — Fetch PR data
 
Run: `node scripts/fetch-pr-diff.js --pr $PR_URL --output /tmp/pr-data.json`
 
If script exits with code 401: GITHUB_TOKEN missing. Stop.
If script exits with code 404: incorrect PR URL. Ask the user to verify.
 
## Step 2 — Write the summary
 
Structure:
**What changed:** [1-2 sentences, no technical jargon]
**Why it matters:** [Business impact]
**Risk level:** Low / Medium / High — [one-sentence justification]
**Monitor after deploy:** [Specific metrics, or "None"]
 
Do not include: file names, function names, line numbers.

# Install the official validator
npm install -g skills-ref
 
# Validate
skills-ref validate ./pr-summary-for-stakeholders

Level 1 — Startup (~100 tokens per skill)
  name + description only
  → Lightweight index, even with 100 skills installed
 
Level 2 — On activation (<5000 tokens recommended)
  Full SKILL.md body — loaded when description matches
  → Practical limit: 500 lines maximum per SKILL.md
  → Beyond that: move content to references/
 
Level 3 — On demand (cost on use)
  scripts/    — executed when a step calls them
  references/ — loaded when a step references them
  assets/     — templates and data files

import anthropic
 
client = anthropic.Anthropic()
 
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{
        "role": "user",
        "content": "Create an Excel file with a quarterly budget"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

curl "https://api.anthropic.com/v1/skills?source=anthropic" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02"

~/.codex/skills/
├── code-reviewer/
│   └── SKILL.md
├── git-commit-writer/
│   └── SKILL.md
└── env-doctor/
    ├── SKILL.md
    └── references/
        └── common-issues.md

~/.codex/skills/my-skill/
├── SKILL.md          ← Open standard — portable everywhere
└── openai.yaml       ← Codex only — ignored by Claude Code and Gemini CLI

# openai.yaml — Codex-specific metadata
policy:
  allow_implicit_invocation: false   # false = explicit $skill-name invocation required
 
dependencies:
  tools:
    - type: "mcp"
      value: "github"
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.github.com/mcp"

# Official OpenAI skills
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/<skill-name>
 
# Community skills — manual install
mkdir -p ~/.codex/skills
git clone <repo-url> ~/.codex/skills/<skill-name>
 
# Verify installation
ls ~/.codex/skills/<skill-name>/SKILL.md

# AGENTS.md
 
## Mandatory skill usage
 
- Use `$implementation-strategy` before editing runtime or API changes.
- Run `$code-change-verification` when runtime code, tests, or build behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when work is ready for review.
 
## Build and test commands
 
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm lint`, `pnpm test`
 
## Compatibility rules
 
- Preserve positional compatibility for public constructors and dataclass fields.

# Audit checklist — non-negotiable before production install
 
# 1. Read SKILL.md in full — look for out-of-scope instructions
cat ~/.codex/skills/<skill-name>/SKILL.md
 
# 2. Read every script — look for network calls and filesystem access
cat ~/.codex/skills/<skill-name>/scripts/*.sh
cat ~/.codex/skills/<skill-name>/scripts/*.py
 
# 3. Search for hardcoded URLs across all files
grep -r "http" ~/.codex/skills/<skill-name>/
 
# 4. Search for credential and sensitive variable access
grep -r "API_KEY\|TOKEN\|SECRET\|PASSWORD\|~/.ssh\|/etc/passwd" \
  ~/.codex/skills/<skill-name>/
 
# 5. Test in a sandbox repo before production
# 6. Pin to a specific commit SHA — never "latest" from an unaudited source

# Too vague — fires on too many things
description: Run the mandatory verification stack.
 
# Production-grade — says when AND on what (OpenAI Agents SDK pattern)
description: >
  Run the mandatory verification stack when changes affect runtime code,
  tests, or build/test behavior. Do not trigger for docs-only changes.

## Step 2 — Verification
 
Run: `scripts/verify.sh --mode strict --output /tmp/report.json`
 
If exit code 0: proceed to Step 3
If exit code 1: read /tmp/report.json, report errors, stop
If exit code 2: timeout — rerun with --mode fast, document the result

## Error handling
 
If validation script exits with code > 0:
- Do NOT proceed to the next step
- Return errors in this exact format:
  Validation failed. [N] critical errors:
  - [Error] in [location]
  Fix these errors before continuing.
 
If external API returns 503:
- Use the cached fallback in assets/fallback-rules.json
- Add a visible warning: "Cached data from [date]. Verify before submission."

---
name: financial-report-generator
metadata:
  version: "1.2.0"
  changelog: "1.2.0 - OHADA (TG/CI/SN) · 1.1.0 - cache fallback · 1.0.0 - IFRS+GAAP"
---

release-review/
├── SKILL.md
├── scripts/
│   └── fetch-diff.sh
└── references/
    └── release-criteria.md

---
name: release-review
license: Apache-2.0
compatibility: Requires git
metadata:
  version: "1.0.0"
  author: "Luc K. SEGBEDZI"
  repo: "github.com/Komluc/agent-skills-production"
description: >
  Prepares a complete release review by comparing the previous git tag with
  main. Use when work is complete and ready for a release candidate.
  Do not use for intermediate reviews during active development.
---
 
## Step 1 — Fetch the diff
 
Run: `scripts/fetch-diff.sh --output /tmp/release-diff.txt`
 
Exit codes:
- exit 0: diff generated — continue to Step 2
- exit 1: no previous git tag found — ask the user to create a tag first
- exit 2: git not available in PATH — stop and inform the user
- exit 3: missing argument — skill configuration error
 
## Step 2 — Analyze the diff
 
Read `/tmp/release-diff.txt`. Inspect for:
- Breaking changes in public APIs
- Behavioral regressions
- Missing migration notes for breaking changes
- Feature removals without prior deprecation
 
See `references/release-criteria.md` for complete criteria by change type.
 
## Step 3 — Release decision
 
Start from "safe to release". Move to "blocked" only on concrete evidence in the diff.
 
Required output format:
 
Release readiness review
 
Release call: GREEN — safe to release
OR
Release call: BLOCKED
 
[If BLOCKED only]
Unblock checklist:
- [ ] [Specific action — cite the exact diff line as evidence]
 
Every blocked item must point to evidence in the diff. A BLOCKED call without evidence is invalid.

#!/usr/bin/env bash
# fetch-diff.sh
# Usage: fetch-diff.sh --output <path>
#
# Exit codes:
#   0 — success, diff written to <path>
#   1 — no previous git tag found
#   2 — git not available in PATH
#   3 — missing --output argument
 
set -euo pipefail
 
# ── Check git availability ───────────────────────────────────────────────────
if ! command -v git &>/dev/null; then
  echo "ERROR: git not found in PATH" >&2
  exit 2
fi
 
# ── Parse arguments ──────────────────────────────────────────────────────────
OUTPUT=""
while [[ $# -gt 0 ]]; do
  case "$1" in
    --output)
      OUTPUT="$2"
      shift 2
      ;;
    *)
      echo "ERROR: unknown argument: $1" >&2
      echo "Usage: $0 --output <path>" >&2
      exit 3
      ;;
  esac
done
 
if [[ -z "$OUTPUT" ]]; then
  echo "ERROR: --output is required" >&2
  echo "Usage: $0 --output <path>" >&2
  exit 3
fi
 
# ── Find previous tag ────────────────────────────────────────────────────────
PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
 
if [[ -z "$PREV_TAG" ]]; then
  echo "ERROR: no previous git tag found." >&2
  echo "Create a tag first: git tag v0.0.0 <commit-sha>" >&2
  exit 1
fi
 
# ── Generate diff ────────────────────────────────────────────────────────────
echo "Comparing: $PREV_TAG → HEAD"
git diff "$PREV_TAG"..HEAD --stat --no-color >  "$OUTPUT"
git diff "$PREV_TAG"..HEAD --no-color        >> "$OUTPUT"
 
echo "Diff written to: $OUTPUT"
echo "Lines: $(wc -l < "$OUTPUT")"

# Release Criteria by Change Type
 
## Public APIs
- Removing an existing parameter → BLOCKED (breaking)
- Changing a return type → BLOCKED (breaking)
- Adding an optional parameter → OK
- Deprecation with notice → OK if migration note is present
 
## Runtime compatibility
- Dropping support for a version (e.g. Python 3.9) → MODERATE
  Verify release notes explicitly mention it
- Major dependency change → MODERATE
 
## General rule
Start from GREEN. Every move to BLOCKED must cite a line from the diff.
A BLOCKED call without evidence in the diff is invalid.

# Install the official validator
npm install -g skills-ref
 
# Validate structure and frontmatter
skills-ref validate ./release-review
 
# Make script executable
chmod +x release-review/scripts/fetch-diff.sh
 
# Dry run in a repo with at least one tag
cd your-test-repo
git tag v0.0.0 HEAD~5   # create a tag if needed
bash ../release-review/scripts/fetch-diff.sh --output /tmp/test-diff.txt
cat /tmp/test-diff.txt