Skill CreatorSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# Choose finance-skill-creator when prompted.
npx plugins add himself65/financ

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: skill-creator
description: >
  Create, improve, and evaluate agent skills (SKILL.md plus reference files). Use this
  skill whenever the user wants to build, scaffold, or design a new skill, improve or
  fix an existing skill that isn't working well, score or benchmark a skill's quality
  or run evals on it, or turn a repeated manual workflow into a skill ("I keep doing
  X manually", "can you remember how to do X", "turn this into a skill").
---

# Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill covers the whole lifecycle: planning what the skill should do, writing SKILL.md and reference files, scoring quality against a rubric, and iterating until the skill meets production standards.

**Philosophy:** A great skill is precise, not long. Its description routes the right requests to it. Its body gives the model the context it can't get anywhere else — the environment, tool contracts, defaults, domain judgment, and the reasons behind each constraint — and leaves out what a capable model already does on its own. Current Claude models follow instructions closely and literally, so every line gets acted on: an over-scripted or shouting skill produces rigid, over-cautious output, while a clear goal and quality bar let the model plan the work itself. `references/writing-guide.md` covers this in detail.

**Runtime adaptation:** Skills that touch external tools should detect what is installed, authenticated, and reachable at runtime and adapt, rather than assuming a single method. Offer fallback paths where real alternatives exist. See `references/dynamic-calling.md` for the pattern catalog.

---

## Step 1: Understand What the User Wants

Classify the request into one of these modes:

| User Intent | Mode | Jump To |
|---|---|---|
| Create a brand-new skill | **Create** | Step 2 |
| Improve / fix an existing skill | **Improve** | Step 6 |
| Evaluate / score a skill's quality | **Evaluate** | Step 7 |

If ambiguous, ask: "Do you want to create a new skill, improve an existing one, or evaluate one?"

### Gather Requirements (for Create mode)

Before writing anything, answer these questions (ask the user if unclear):

| Question | Why it matters |
|---|---|
| What task does the skill automate? | Defines the core workflow |
| Who is the target user? | Determines complexity and terminology level |
| What tools/APIs/CLIs does it use? | Determines dependencies and platform restrictions |
| What does the user provide as input? | Defines parameters and defaults |
| What should the output look like? | Defines the output contract |
| Does it need API keys or credentials? | Determines `required_environment_variables` |
| Should it work on Claude.ai or only CLI? | Determines platform field and dynamic commands |

---

## Step 2: Plan the Skill Architecture

Before writing SKILL.md, plan the structure. Read `references/architecture-patterns.md` for detailed guidance on each pattern.

### Choose a Structural Pattern

| Pattern | When to use | Shape | Example |
|---|---|---|---|
| **Linear** | Single workflow, no branching | Setup → fetch → analyze → respond | earnings-preview |
| **Router** | Multiple sub-tasks under one umbrella | Setup + routing table + sub-skills | stock-correlation (4 sub-skills), etf-premium |
| **Methodology** | Formal domain framework with real gates | Ordered checks, each able to stop the analysis | sepa-strategy |
| **Widget** | Generates interactive UI output | Extract → compute → render → explain | options-payoff |
| **API Wrapper** | Wraps an external API with many endpoints | Auth + endpoint map + heavy references | fintel-data |

### Plan the Outline

Every skill has three parts:

1. **Setup / detection** — detect available tools, auth state, and runtime environment, and decide which method to use. Skills with no external dependencies can skip this.
2. **The work** — numbered steps where the order genuinely matters (fetch before compute, a gate that can end the analysis), plus the judgment the model has to exercise, stated as goals, criteria, and domain heuristics rather than a script.
3. **Respond to the user** — the output contract: what the answer leads with, what it must contain, which caveats apply, and any verdict scale.

If a skill needs more than about nine steps, split it or use the Router pattern.

### Plan the Detection Flow

Skills that touch external tools should start with a runtime detection flow. Read `references/dynamic-calling.md` for all patterns. The detection flow answers:

| Question | How to detect | Decision |
|---|---|---|
| Is the CLI tool installed? | `command -v tool` | CLI path vs Python fallback |
| Is the user authenticated? | `tool auth status` / `echo $API_KEY` | Skip auth setup vs guide through it |
| Which runtime has the library? | `import lib` in terminal vs execute_code | Route to correct runtime |
| Is a richer tool available? | `gh --version` vs `git --version` | Rich path vs minimal path |
| Is live data reachable? | `curl -s endpoint` | Live data vs cached/default |

The detection output feeds a **decision tree** that the rest of the skill follows — check rather than assume.

### Plan Reference Files

Decide what goes in SKILL.md vs references/:

| In SKILL.md (under ~250 lines) | In references/ |
|---|---|
| Workflow and decision points | Detailed API documentation |
| Routing/decision tables | Code templates (>20 lines) |
| Parameter defaults table | Formulas and edge cases |
| Output contract | Troubleshooting database |
| Quick examples (1-3) | Comprehensive examples (4+) and dated datasets |

---

## Step 3: Write the SKILL.md

Read `references/writing-guide.md` for detailed instructions on writing each section. Read `references/frontmatter-guide.md` for the complete YAML field reference.

### Key Rules

1. **Frontmatter first**: `name` (lowercase-hyphenated, max 64 chars) and `description` (max 1024 chars, no angle brackets) are required. The description is routing text that rides along

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.