Skip to content

Add universal skills-creator package with scaffold and validator#4

Draft
Codex wants to merge 2 commits intomainfrom
codex/refine-skills-creator-package
Draft

Add universal skills-creator package with scaffold and validator#4
Codex wants to merge 2 commits intomainfrom
codex/refine-skills-creator-package

Conversation

@Codex
Copy link
Copy Markdown

@Codex Codex AI commented Mar 18, 2026

Replaces the legacy create-skill guidance with a production-ready, platform-agnostic skills-creator package that aligns with the refined structure and lifecycle.

  • SKILL.md: Seven-phase lifecycle (discover → scaffold → author → scripts → evaluate → platform check → security) with progressive disclosure rules, pre-ship gate, and references to supporting assets.
  • Assets/References: Added templates for SKILL and eval scenarios plus PATTERNS, PLATFORMS, SECURITY, and ANTIPATTERNS guides to keep heavy content out of SKILL.md.
  • Scripts: New scripts/scaffold.py enforces naming rules and generates SKILL/eval scaffolds; scripts/validate.py checks frontmatter, naming/description limits, line counts, reference depth, and eval counts.
  • Live docs: Updated current focus, todo, and progress to reflect the new skills-creator objective and completion; removed the old create-skill folder.

Example (scaffold + validate):

python3 scripts/scaffold.py processing-pdfs
python3 scripts/validate.py processing-pdfs --full
Original prompt

I would like to refine and level up the create-skills.

Read below analyses:

"""
Now I have the complete picture from Anthropic's official docs. Here is the fully refined, production-perfect skills-creator package.


Final Folder Structure

skills-creator/
├── SKILL.md                    ← Entry point (≤500 lines, ≤5k tokens)
├── scripts/
│   ├── scaffold.py             ← Generates skill folder + boilerplate
│   └── validate.py             ← Lints frontmatter, structure, constraints
├── references/
│   ├── PATTERNS.md             ← Progressive disclosure patterns
│   ├── PLATFORMS.md            ← Per-surface runtime constraints
│   ├── SECURITY.md             ← Security audit checklist
│   └── ANTIPATTERNS.md        ← Common authoring mistakes
└── assets/
    ├── skill_template.md       ← Minimal valid SKILL.md boilerplate
    └── eval_template.md        ← Test scenario template

SKILL.md

---
name: skills-creator
description: >
  Scaffolds, authors, validates, and iterates on SKILL.md packages
  following Anthropic's official Agent Skills spec and authoring guidelines.
  Use when the user asks to create, design, review, refine, or evaluate
  an agent skill or SKILL.md file.
license: MIT
compatibility: >
  Claude Code (full support); Claude API (no network, no runtime installs);
  Claude.ai (varying network). Python 3.9+ required for scripts.
allowed-tools: Bash(python3:*) Read Write
meta
  author: your-org
  version: "2.0"
  spec: anthropic-agent-skills-2025-10-02
---

# Skills Creator

Guides the complete lifecycle of a SKILL.md package: discover → scaffold →
author → write scripts → evaluate → ship. Follow all phases in order.
Never skip Phase 5 (Evaluate).

---

## Phase 1 — Discover

Answer all five questions before writing a single line:

1. **Single responsibility** — What is the one thing this skill does?
2. **Failure case** — What specific task fails without this skill?
3. **Dependencies** — What tools, packages, or external services are needed?
4. **I/O contract** — What does the user provide? What is the output?
5. **Fragility** — How sensitive is execution to variation? (determines instruction style)

Stop and ask the user if any answer is unclear. Vague skills produce vague behavior.

---

## Phase 2 — Scaffold

Generate the folder structure and boilerplate:

```bash
python3 scripts/scaffold.py <skill-name>

Naming rules (Anthropic spec):

  • Gerund form preferred: processing-pdfs, analyzing-logs, managing-git
  • Lowercase letters, numbers, hyphens only
  • Max 64 characters
  • No leading, trailing, or consecutive hyphens
  • Forbidden words: anthropic, claude, helper, utils, tools
  • Folder name must exactly match the name field in frontmatter

Minimum valid output structure:

<skill-name>/
├── SKILL.md          ← Required
└── scripts/          ← Add if execution steps exist

Phase 3 — Author SKILL.md

Frontmatter

Only name and description are required. Add optional fields only
when they provide genuine value:

***
name: <gerund-skill-name>
description: >
  [Third-person verb phrase. What it does. When to use it.]
  Max 1,024 chars. No XML tags.
license: MIT                         # if distributing
compatibility: Requires pdfplumber   # if env-specific
allowed-tools: Bash(python3:*) Read  # if pre-approving tools
meta
  author: your-org
  version: "1.0"
***

Description formula

"[Verb phrase]. Use when [trigger condition(s)]."

✅ Good ❌ Bad
"Extracts tables from PDFs. Use when the user shares a PDF." "I can help with PDFs" — first person
"Analyzes CSV data and generates reports. Use when..." "A helpful CSV tool" — no trigger
Third-person only No XML tags ever

Body structure

Calibrate instruction style to task fragility:

Fragility Style Example
Low Natural language heuristics "Choose the best extraction method for the file type"
Medium Parameterized pseudocode run extract.py --mode auto --output json
High Exact verbatim commands "Run exactly: python3 scripts/run.py --strict. Do not modify."

Standard section order:

  1. Preconditions — what must be true before starting
  2. Steps — numbered, imperative, one action per step
  3. Tools — which tools to call and when (use fully-qualified MCP names: BigQuery:bigquery_schema)
  4. Output — artifact type, format, and destination
  5. Edge Cases — inline if ≤3 lines; otherwise link to references/

Progress checklist for multi-step tasks:

Task Progress:
- [ ] Step 1: [action]
- [ ] Step 2: [action]
- [ ] Step 3: Validate output
- [ ] Step 4: Fix errors and re-validate
- [ ] Step 5: Only proceed when validation passes

Progressive disclosure rules

Level Content Token budget When loaded
1 — Metadata YAML fro...

@Codex Codex AI changed the title [WIP] Refine and enhance skills-creator package Add universal skills-creator package with scaffold and validator Mar 18, 2026
@Codex Codex AI requested a review from thompson0012 March 18, 2026 04:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants