Skill Gen

Scope guard: This skill is not available in LITE scope projects. LITE scope does not support skills or knowledge bundles. If the target project’s AGENTS.md contains agentfs-scope: lite, refuse with a clear message.

Create new skills, modify and improve existing ones with built-in AgentFS conventions. Operates in three modes: simple (quick scaffold), advanced (full eval/iterate/optimize loop using upstream Anthropic skill-creator), and skill check (audit existing skills against five quality principles). Default mode is simple; use advanced when requesting “thorough”, “with evals”, or “production quality”.

This is a proxy skill that operates in three modes:

Mode When What Happens
Simple (default) Quick utility skills, SOPs, small workflows Scaffold + write + AgentFS post-creation checklist
Advanced “advanced”, “thorough”, “with evals”, “production quality” Full upstream eval/iterate/optimize loop + AgentFS checklist
Skill Check “check skill”, “skill check”, “audit skill” Audit existing skill against five quality principles

Mode Selection

Detect mode from user’s language:

When in doubt, ask: “Do you want a quick skill scaffold, or a thorough process with test cases and evaluation?”

Skill Design Principles

Before creating any skill, understand the three foundational principles that govern skill architecture. These apply to both Simple and Advanced modes.

Non-Interactive Scripts

Scripts under scripts/ MUST be non-interactive — they MUST NOT use read, select, interactive prompts, or any mechanism that blocks waiting for stdin. All inputs MUST be accepted via CLI arguments, environment variables, or input files.

Agent-as-Orchestrator

Skills implement a three-layer separation of concerns:

Layer Responsibility Interactive?
SKILL.md Defines the process — steps, decision points, gates N/A (blueprint)
Agent Orchestrates flow, mediates user interaction, feeds data between steps ✅ Conversationally
Scripts Execute deterministic, repeatable actions ❌ Never

The agent handles ambiguous inputs, clarifications, approvals, and error explanations. Scripts handle validation, API calls, and data transformations. SKILL.md is the contract between them.

Rule of thumb: Loose steps → write instructions; fragile steps → write code. When logic is approximate and benefits from model judgment, describe it in SKILL.md prose. When logic is precise, fragile, or must be consistent across runs, implement it as a script.

Business Process Modeling

Skills can model multi-step processes with human interaction points. Interactivity belongs in the agent ↔ user conversation, not in script execution. A process skill defines:

This preserves all guardrails — scripts stay idempotent (Guardrail #6), the SKILL.md is the process documentation, each script is independently testable, and the same scripts can be reused by other skills or automated jobs with pre-known inputs.

Simple Mode

Step 1 — Capture Intent

Understand what the skill should do. The current conversation may already contain the workflow to capture. Extract:

  1. What should this skill enable the agent to do?
  2. What are the steps involved?
  3. What inputs does it accept?
  4. What does success look like?
  5. Are there scripts to generate or reference docs to include?

Anti-pattern: Generic Mush. Do NOT instruct the agent to do things it already knows from base training (standard error handling, basic input validation, common patterns). A skill’s value comes from domain expertise the model cannot access on its own.

Sources of real expertise:

Gotchas section. Include a “Gotchas” or “Known Issues” section in SKILL.md capturing environment-specific anomalies, historical corrections, and non-obvious behaviors discovered during development or usage. This is often the highest-value section in a skill — hard-won factual knowledge that prevents the agent from repeating past mistakes.

Step 2 — Determine Scope

Step 3 — Create Directory Structure

SKILL_DIR="$HOME/.agents/skills/<skill-name>"  # or ./.agents/skills/ for PROJECT
mkdir -p "$SKILL_DIR/scripts"
# mkdir -p "$SKILL_DIR/references"  # only if needed

Step 4 — Write SKILL.md

Generate a SKILL.md with this exact structure:

---
name: <skill-name>
description: >
  <signal phrase 1>, <signal phrase 2>, <signal phrase 3>,
  <signal phrase 4>, <signal phrase 5>
argument-hint: "<usage hint>"
compatibility: "<requirements, if any>"
metadata:
  author: agentfs
  version: "1.0.0"
  tags: [<relevant-tags>]
user-invocable: true
disable-model-invocation: false
---

# <Title>

<Opening paragraph — human-readable explanation of what this skill does,
why it exists, and when to use it. This is the hydrated context that
the signal-phrase description cannot convey.>

## Prerequisites

- <List of requirements>

## Steps

1. **Step name**
   Description and commands.

2. **Step name**
   Description and commands.

## Gotchas

- <Environment-specific anomalies, historical corrections,
  non-obvious behaviors discovered during development or usage>

## Verification

- [ ] <How to confirm success>

## Changelog

> See [CHANGELOG.md](/agentfs/skills/skill-gen/CHANGELOG.html) for version history.

Description as signal phrases:

The description field contains signal phrases — the trigger phrases the LLM uses to match user intent to this skill. It is loaded into every session via the built-in skills listing, making it the only metadata always in the agent’s context.

Opening paragraph:

Since the description field contains signal phrases (not prose), the SKILL.md body MUST include a hydrated opening paragraph immediately after the # Title heading. This paragraph provides the rich human-readable context: what the skill does, why it exists, and when to use it.

Writing guidance:

Step 5 — Write Scripts (if applicable)

Generate executable scripts under scripts/:

#!/usr/bin/env bash
# <script-name>.sh — <one-line description>
# Usage: bash <script-name>.sh [args]
set -euo pipefail
# ... implementation ...

Step 6 — AgentFS Post-Creation Checklist

MUST complete ALL of these after creating/updating the skill:

⛔ GATE — Principle waiver requires explicit permission. If you believe Principle 4 (Spec/Tests) or Principle 5 (Security) does not apply to this skill, you MUST:

  1. State your reasoning clearly to the user
  2. Get explicit confirmation before omitting the section
  3. Log the waiver in the skill’s CHANGELOG.md entry

Do NOT silently skip. A rationalization in your own reasoning is not a substitute for user confirmation.

Advanced Mode

Advanced mode uses the full Anthropic skill-creator workflow: draft → test → evaluate → iterate → optimize.

Step 1 — Fetch Upstream

Ensure the upstream skill-creator is cached locally:

bash ~/.agents/skills/skill-gen/scripts/fetch-upstream.sh

This downloads the complete Anthropic skill-creator file structure into ~/.agents/skills/skill-gen/.cache/upstream/.

Step 2 — Load Upstream Instructions

Load the full upstream SKILL.md for detailed instructions:

load_skill(name: "skill-gen/.cache/upstream/SKILL.md")

Step 3 — Follow Upstream Workflow

Follow the upstream instructions for the full lifecycle:

  1. Capture intent — interview the user
  2. Write SKILL.md draft — using upstream’s writing guide
  3. Create test cases — 2-3 realistic test prompts
  4. Run tests — execute and collect results
  5. Evaluate — qualitative (user review) + quantitative (assertions)
  6. Iterate — improve based on feedback, repeat
  7. Optimize description — triggering accuracy loop (if available)

Agent Compatibility Notes for Upstream

The upstream skill-creator was written for Claude Code. When using with a different agent, apply these adaptations:

Upstream Feature Claude Code Goose / Other Agents
Subagents spawn subagent Use Goose orchestrator extension if available, otherwise run test cases sequentially
claude -p CLI Native Skip description optimization (run_eval.py, run_loop.py, improve_description.py). These scripts hardcode claude -p.
.claude/commands/ Native skill discovery Not applicable — skills discovered via .agents/skills/
Browser viewer open <file> Use --static <path> flag to generate HTML file, then open manually or with xdg-open
Cowork Claude-specific Not applicable
present_files tool Claude-specific Not applicable — skip packaging step

What works everywhere:

Step 4 — AgentFS Post-Creation Checklist

Same as Simple Mode Step 6 — apply the AgentFS post-creation checklist after the upstream workflow completes. The upstream does NOT handle AgentFS conventions (scoping, indexing, logging), so this step is essential.

Updating an Existing Skill

For both modes:

  1. Read the existing SKILL.md first
  2. Preserve the original name field — do not rename
  3. Add a new changelog entry to CHANGELOG.md (do not remove existing entries)
  4. In advanced mode, use the existing skill as the baseline for comparison in the eval loop
  5. Run the AgentFS Post-Creation Checklist (Step 6 / Step 4)

Skill Check Mode

Audit one or more skills against five quality principles. Use when:

Trigger phrases: “skill check”, “scan skill”, “check skill”, “audit skill”, “verify skill quality”

Five Principles

Principle 1 — Accuracy, Consistency & Testability (Code-First)

Skills are procedural memory — prescriptive SOPs verified by execution, auditable traces, and deterministic outcomes. Prefer and leverage deterministic scripts and code as the primary vehicle for accuracy (no ambiguity), consistency (same inputs → same outputs), conciseness (denser than prose), and testability (independently executable). Natural language serves as orchestration glue — connecting, contextualizing, and sequencing the deterministic pieces. Declarative, methodological, and philosophical content belongs in knowledge bundles, not skills.

Inline code boundary: Code in SKILL.md serves two distinct roles:

Rule of thumb: If the agent would bash -c it during execution, it should be a script. If it shows the user what something looks like or provides a manual alternative, it stays inline.

Check for:

Principle 2 — Autonomous & Currency

Skill MUST NOT rely on current session history. It must function in a fresh NEW session without glitches. No obsolete scripts, code, instructions, or content.

Check for:

Principle 3 — Traceable & Well-Formatted

No redundant, conflicting, or obsolete instructions or scripts. Historical content must be distilled to knowledge bundles with links from the skill’s changelog.

Check for:

Principle 4 — Verifiable Specification & Test

A description of purpose is not sufficient. The skill MUST have a list of verifiable specification items that clearly and concisely prescribe what the skill can do. Associated with each spec item are testcases — preferably deterministic scripts/code, or at minimum unambiguous instructions with expected results.

Check for:

Example Specification section:

## Specification

| ID | Capability | Verifiable By |
|:--:|-----------|---------------|
| S1 | List all model containers on both hosts | `scripts/list.sh` outputs status table |
| S2 | Start model by alias on correct host/port | `scripts/start.sh g350m` → HTTP 200 on port 10000 |
| S3 | Stop model by alias | `scripts/stop.sh g350m` → container status Exited |

## Tests

| Test | Spec | Command | Expected Result |
|:----:|:----:|---------|----------------|
| T1 | S1 | `scripts/list.sh` | Table showing 5 models with status |
| T2 | S2 | `scripts/start.sh g350m && scripts/test.sh g350m` | HTTP 200, model=granite-4.0-350m |
| T3 | S3 | `scripts/stop.sh g350m && scripts/status.sh g350m` | Container Exited |

Principle 5 — Security & Trust Boundary

Skills execute local scripts that can read the filesystem, access API keys, and make network calls. Treat third-party skills as external software dependencies. Author-created skills must also minimize their attack surface.

Check for:

Skill Check Procedure

  1. Load the target skill — load_skill(name: "<skill-name>")
  2. Read all supporting files — scripts, references, templates
  3. Apply Principle 1 — verify scripts exist and match SKILL.md; flag inline-only operations as 🔴 critical; flag could-be-script prose as 🟡; flag non-procedural content for knowledge extraction
  4. Apply Principle 2 — check for session dependencies, obsolete references; verify scripts are self-contained
  5. Apply Principle 3 — scan for redundancy, conflicts, obsolete content; check Markdown rendering
  6. Apply Principle 4 — verify Specification and Tests sections exist; check spec coverage and test determinism
  7. Apply Principle 5 — audit scripts for scope overreach, secret handling, unexpected network calls, and prompt injection
  8. Report findings — table of issues with severity (🔴 critical, 🟡 warning, 🟢 info) and recommended fix
  9. Fix — apply fixes with user approval; version bump; changelog

Report Format

## Skill Check Report: <skill-name>

| # | Principle | Severity | Finding | Fix |
|:-:|:---------:|:--------:|---------|-----|
| 1 | P1 Accuracy | 🔴 | ... | ... |
| 2 | P4 Spec/Test | 🟡 | ... | ... |
| 3 | P5 Security | 🟡 | ... | ... |

Upstream Source

Item Value
Repository anthropics/skills
Path skills/skill-creator/
License See LICENSE.txt in cached upstream
Cache location ~/.agents/skills/skill-gen/.cache/upstream/
Cache refresh Every 7 days, or fetch-upstream.sh --force

Changelog

See CHANGELOG.md for version history.