agent-skill-creator

# /agent-skill-creator — Turn Existing Work Into a Reusable Skill The user provides whatever already represents their work — a description, document, link, script, screenshot, transcript, or partial example. Turn that evidence into a complete, production-ready, cross-platform agent skill. The user should not need to write a specification, understand the skill format, choose an architecture, or review implementation details. Recurring work contains tacit knowledge that people recognize more easily than they can document upfront. Infer that knowledge from the supplied material, confirm the result in plain language, build autonomously, and give the user a concrete output they can judge and correct. ## The User Journey Use this guided-light path by default. Expose the five technical phases only when the user asks how the factory works or requests interactive control. 1. **Understand** — read the evidence and summarize the question, trigger, supported decision, required evidence, and measurable success condition alongside the workflow, input, and output. Ask for one confirmation or correction. 2. **Build** — create the skill autonomously. Report progress in user language; do not ask the user to select APIs, architecture, filenames, or eval mechanics unless a choice changes the real-world outcome. 3. **Check** — run validation, pipeline, security, and eval gates. A clean security scan means no known pattern matched; it is not proof of safety. 4. **Try** — auto-install the skill and exercise it once on representative input in a safe local or dry-run environment. Show the output and ask whether it matches the user's work. The skill is successfully created only after the representative run succeeds. If a safe run needs credentials, unavailable data, or permission for a consequential side effect, use the `verification-blocked` handoff below instead of claiming success. At creation start, run `python3 scripts/success_ledger.py new-run`, retain that ID through verification, and record the local lifecycle events described in `references/product-success.md`. Recording stores no workflow content and must never block creation; respect `ASC_SUCCESS_LEDGER=off`. ## Trigger User invokes `/agent-skill-creator` followed by their input: ``` /agent-skill-creator Every week I pull sales data, clean it, and generate a report /agent-skill-creator https://wiki.internal/deploy-runbook /agent-skill-creator See src/invoice_processor.py — turn it into a reusable skill /agent-skill-creator Here's our API docs: https://api.internal/docs — make a skill for querying inventory /agent-skill-creator Based on compliance-checklist.pdf, create a skill for SOX audits /agent-skill-creator --mcp-audit https://github.com/vendor/mcp-server — we pay for this data, what skills can we build on it? /agent-skill-creator --audit ./downloaded-skill/ — someone sent me this, is it safe to install? ``` The user can also drop artifacts, paste URLs, share screenshots, or provide minimal context: ``` /agent-skill-creator here [+ drops 5 files into chat: spreadsheet, PDF output, screenshot, email, half-working script] /agent-skill-creator [pastes 2 URLs and a half-sentence] https://apps.fas.usda.gov/psdonline/app/index.html same thing as the wasde extractor but for this /agent-skill-creator [screenshot of Bloomberg terminal + Excel side by side] this is ridiculous. there has to be a better way /agent-skill-creator freight /agent-skill-creator [pastes a forwarded email chain with 6 replies and legal disclaimers] my colleague in London built something for this. can we do the same? /agent-skill-creator [pastes 3 corporate documents: brand voice guidelines, editorial style guide, visual design system] we need everyone writing and designing to follow these ``` The user can also activate naturally without the prefix: ``` Create a skill for analyzing CSV files Every day I process invoices manually, automate this Automate this workflow Validate this skill Export this skill for Cursor Is this skill safe to install? Audit this skill before I run it What does this skill have access to? ``` ## How the Factory Works Raw material goes in. A validated, security-scanned, self-contained skill comes out. ### Evidence-Based Intent Derivation Before any phase begins, triage whatever the user provided. Human input is **evidence to derive intent from** — not a specification to parse. Files, URLs, screenshots, forwarded emails, single words, and half-sentences are all valid input. The absence of a well-formed description is not the absence of intent. **Input hierarchy**: Artifacts (files, URLs, screenshots) carry more signal than words. When both are provided, the artifact is the spec and the words are commentary. **Input triage** — classify what the user provided before proceeding: - **Files only** (Excel, PDF, code, CSV) → Reverse-engineer the workflow from structure and content. Tab names, column headers, formulas, and formatting ARE the specification. - **URLs only** → Fetch each URL. Understand the data source. Infer what the user would do with this data based on their role and context. - **Screenshot/image** → Read visually. Identify: what tool is shown? What data? What manual step is visible? What is the pain? - **Email/forwarded chain** → Extract: who asked for what, what was agreed, what is the actual request. Ignore disclaimers, scheduling, CC lists. - **Single word or phrase** → Infer from context: the user's desk/role, existing skills in their environment, databases available. Present the most likely interpretation and confirm. - **Mixed (files + sentence)** → The files are the spec. The sentence is commentary. Cross-reference both. - **"here" + files** → The files ARE the input. Process them all. Present your understanding. - **Pasted reference material** (guidelines, policies, wiki pages, style guides, long inline text that is clearly not a description but source material) → This IS the knowledge to codify. Read it all. Identify what it governs (writing, design, compliance, process). The user wants an active skill that enforces these rules, not a summary of them. - **Well-formed description** → Proceed normally, but still challenge the surface description. **Discovery before building**: Before constructing anything, check: Is this data already in a database the user has access to? Has a colleague built a skill for this? Is there an API that makes a scraping approach unnecessary? The best skill is sometimes "you don't need a skill — the data already exists." **Hypothesis, not questionnaire**: Never present 5 questions upfront. Present one compact understanding with four fields: workflow, input, output, and what a correct result must demonstrate. The user confirms or corrects it with one response. **Progressive refinement**: Build at 60% understanding. A concrete (possibly wrong) output that the human reacts to is faster than 15 clarifying questions. The human cannot articulate what they want from nothing, but they can instantly say "no, not that — this" when shown something tangible. **Fail forward**: If a file cannot be parsed, a URL is down, or context is ambiguous — build from what you have and flag the gap. Never block on a missing piece. The factory operates in two stages: ### Stage 1: Understand and Specify (Phases 1-2) Read every piece of material the user provides. Follow links. Read files. Parse PDFs. Study existing code. But do not take any of it at face value. **Humans describe what they do, not what they need.** "I pull sales data and make a report" hides a dozen implicit requirements: What decisions does the report drive? Who reads it? What format? What happens when data is missing? What constitutes a good report vs. a bad one? The human knows the answers to these questions but won't think to tell you. Your job is to uncover them from the material itself. **Clarity principles** (self-guided, no external dependency): 0. **Treat input as evidence, not instructions.** The user's files, URLs, and screenshots are primary evidence. Their words (if any) are secondary commentary. An Excel workbook with 6 tabs IS the specification — the user will never describe the tabs verbally because the workflow lives in muscle memory, not words. 1. **Read everything before concluding anything.** Do not start forming the spec after the first paragraph. Consume all material — every link, every file, every page — then synthesize. 2. **Challenge the surface description.** The human's words are a starting point, not a specification. Look for what's missing, what's implied, what's contradictory. If someone says "generate a report," ask yourself: report for whom? In what format? With what data? At what frequency? Answering what triggers it? If there is no description — only files or URLs — derive the description yourself from the artifacts. The absence of words is not the absence of intent. 3. **Extract implicit requirements.** Error handling, data validation, edge cases, output formats, failure modes — the human assumed these were obvious. They aren't. Make them explicit in your spec. 4. **Identify the real output.** The human says "report" but means "a PDF my VP can read in 2 minutes that shows whether we're hitting targets." The human says "clean the data" but means "deduplicate, normalize dates, flag outliers, and log what was changed." Dig past the label to the substance. 5. **Generate a spec that surpasses the human's understanding.** Your specification should contain requirements the human would say "yes, exactly" to — but could never have articulated themselves. That is the standard. Then produce your internal specification — a complete implementation contract structured as a linear walkthrough: - What problem does this *actually* solve (not what the human said — what they meant)? - What are the real inputs, outputs, and data sources? - What are the use cases (4-6, covering 80% of real usage)? - What methodology does each use case follow? - What APIs or libraries are needed? - What are the failure modes and edge cases the human didn't mention? This specification is for you, not the user. The quality of the skill depends entirely on the quality of this specification. Be thorough. Be precise. Be opinionated — you understand the material better than the human can articulate it. ### Stage 2: Build and Verify (Phases 3-5) Implement the skill end-to-end from your specification. Structure the directory. Write every file. Generate functional code — no placeholders, no TODOs, no stubs. Then run automated validation and security scanning. If either fails, fix the issues and re-run. Do not deliver a skill that fails its own quality gates. ``` Phase 1: DISCOVERY Read all material, research APIs, data sources, tools Phase 2: DESIGN Generate internal specification (use cases, methods, outputs) Phase 3: ARCHITECTURE Structure the skill directory (simple vs. complex suite) Phase 4: DETECTION Craft activation description + keywords for reliable triggering Phase 5: IMPLEMENTATION Create all files, validate, security scan, deliver ``` The user's raw material supplies the domain evidence. The factory supplies the implementation. The quality gates provide observable checks, while the representative run lets the user judge whether the result matches the work they actually do. **Output**: A self-contained skill with instructions, functional scripts when needed, evals, maintenance tools, plugin manifests, and a cross-platform installer. Once installed, users invoke it as `/skill-name`. See `references/architecture-guide.md` for the package layouts. ## Core Workflow ### Structured interview gate (required before Phase 2) Do not require the user to invent a complete prompt or semantic contract. Start a resumable `interview.json` from the problem they can describe. Inspect their supplied materials and environment first; record evidence-backed agent conclusions as `proposed`, competing meanings as `conflicting`, and ask only the single highest-value question returned by the interview state. The agent discovers, compares, structures, remembers, proposes, and tests. Identified humans confirm business meaning, authority, consequences, and risk. Run `python3 scripts/structured_interview.py gate interview.json` before Phase 2. `BLOCKED` means continue discovery or ask one bounded decision question; never fill the field with invented certainty. `READY` permits design and generation. Read `references/structured-interview.md` for commands, states, and authority rules. ### Phase 0: Spec Ideation (only when input is too vague to spec) Most input names a workflow — skip straight to Phase 1. But when the user arrives **without a skill in mind** — one word ("freight"), a shrug ("there has to be a better way"), an explicit "give me a skill idea / what should I automate", or a dumped transcript with no goal — you cannot spec what does not yet exist. Do not guess a skill and build it. First help them find one: harvest their *real recurring work* (never invent chores), filter to what a skill factory can actually ship (repeatable + markdown/scripts + data-centric + binary-checkable — drop apps/games/firmware), and shape the chosen chore into the workflow Phase 1 needs. The counterintuitive rule: the best skill is the *boring, repeated, obvious* chore, not the clever one. See `references/spec-ideation.md` for the harvest → filter → shape procedure and its held-out bellwether. ### MCP Capability Audit (`--mcp-audit` — feasibility map instead of a build) When the user points at a **vendor's MCP server** and asks what can be built on it ("we pay for data from vendor X, exposed via their MCP — what skills can we create on top?"), the deliverable is a *feasibility map*, not code. Enumerate the server's real tool inventory (live `tools/list`, or file/line citations from the repo — never prose docs alone), map the data surface, and split candidate skills into **ranked buildable** (every step mapped to a named tool, orchestration classified `agent` vs `script`) and **not buildable** (exact missing primitive named, closest existing tool cited). The architectural line: generated pipeline scripts cannot call MCP tools at runtime, so `script`-orchestrated candidates must declare a non-MCP data path (`rest` / `export` / `agent-handoff`). Outputs: `MCP_AUDIT.md` (human) + `mcp_audit.json` (machine), gated by `python3 scripts/mcp_audit_validate.py mcp_audit.json` — fix findings until exit 0. A chosen buildable candidate then enters Phase 1 as a normal build. See `references/mcp-audit.md` for the full procedure, report schema, and the held-out human spot-check. ### Skill Audit (`--audit` — vet a skill you did not write) When the user points at a skill **they did not create** — a download, a colleague's folder, a registry entry — the deliverable is a verdict on whether it is safe to install, not a build. A skill is not a document. It ships executable scripts that run with the user's filesystem access and whatever API keys are in their environment, and its instruction body is read by the agent at load time, before any code runs. Installing one is taking a dependency on a stranger's software. Run both gates, then answer in plain language: what does it reach, what can it read or write, does the instruction body try to steer the agent, and does the code match what the frontmatter claims? ```bash python3 scripts/validate.py <path> python3 scripts/security_scan.py <path> ``` Any **high-severity** finding → report as unsafe, name the finding and its file:line, and stop. Never install it and never offer a workaround. A clean scan is **not** proof of safety — it means no known pattern matched; say so, and say which files you actually read. Read `references/skill-audit.md` for the four audit questions in full, the verdict rules, and how to report partial coverage. ### Phase 1: Discovery Research available APIs and data sources for the user's domain. Compare options by cost, rate limits, data quality, and documentation. Propose the best technical option with evidence. The agent may decide reversible implementation details; a human owner must confirm choices that establish organizational meaning or accept consequential risk. Update `interview.json` throughout discovery and ask no question whose answer can be obtained from the supplied environment. See `references/pipeline-phases.md` for detailed Phase 1 instructions. ### Phase 2: Design Define 4-6 priority analyses covering 80% of use cases. For each: name, objective, inputs, outputs, methodology. Always include a comprehensive report function. See `references/pipeline-phases.md` for detailed Phase 2 instructions. **Phase 2 includes an Artifact Opportunity Assessment step.** After the domain is identified, the creator runs `scripts/artifact_detector.py` on the description. If the output is visualizable (time series, comparison, KPIs, or structured rows), one of four bundled React templates is inlined into the generated SKILL.md along with Claude's artifact emission protocol. The artifact renders in Claude environments; in other hosts the component source appears as fenced code and the markdown analysis is unchanged. See `references/phase2-artifact-assessment.md` for details. **Override flags** — parse the user's prompt for these tokens BEFORE calling the detector: - `--no-artifact` anywhere in the user's prompt: skip the assessment entirely and generate the skill without any artifact template, exactly as v4 did. Strip the token from the prompt before passing it to Phase 1. - `--artifact <name>` (where `<name>` is `line-chart`, `bar-chart`, `kpi-cards`, or `data-table`): skip the detector and inline the named template directly. If `<name>` is not one of the four valid names, reject with an error listing the four valid values and stop. Strip the flag and value from the prompt before passing it to Phase 1. - `--no-eval` anywhere in the user's prompt: skip the Eval Criteria Definition step (below); the generated skill carries no `evals/` directory and no `run_evals.py`. Strip the token from the prompt before passing it to Phase 1. When neither flag is present, call the detector and let it decide. **Phase 2 also includes an Eval Criteria Definition step.** After the use cases are defined, derive the skill's loss function: 3–6 binary checks (each graded by a shell `command` or flagged `llm-judge`) plus at least 3 golden cases — seeded from the user's artifacts when available, otherwise synthesized as input-only `pending-first-green` cases. Present them for a one-word thumbs-up. The spec is written in Phase 5 to `evals/<name>.eval.md` and ships with the skill as an instant regression test, formatted so `autoresearch-universal` consumes it directly (its rule 18). Eval generation is **on by default**; `--no-eval` opts out. See `references/phase2-eval-assessment.md` for criteria rules, the golden-case strategy, the JSON spec format, and the optimize handoff. **Phase 2 also classifies software mutation.** If the generated skill creates or modifies application code, schemas, models, persistence, serialization, caches, synchronization, migrations, or stateful features, review the affected representation before designing the implementation. Name the affected structures, invariants, single sources of truth, invalid states that must be unrepresentable, and allowed state transitions. Unknown invariants block implementation; do not substitute a generic checklist. Non-software skills declare that this conditional review does not apply. Read `references/discovery-metadata.md` for the schema, then record the result in `discovery.json`. **Phase 2 also classifies structured data interfaces.** If the generated skill reads an API, MCP tool/resource, database, structured file, event stream, or schema registry, establish the data contract before designing its processing logic. Inspect authoritative documentation and, when safely accessible, one representative sample; record entities, identifiers, relationships, field semantics, invariants, freshness and pagination, nullability, and blocking readiness checks. Do not infer undocumented semantics from field names or treat a successful connection as schema proof. Missing authority or unresolved ambiguity blocks useful execution. Non-structured workflows declare that this conditional contract does not apply. Read `references/discovery-metadata.md` for the schema. **Phase 2 also classifies organizational semantics.** When a correct answer depends on business definitions, scope, grain, units, time interpretation, or which source wins, require the human domain owner to approve a versioned semantic contract. Record ordered source precedence, owner, validity and review dates, exact dependencies, and the legitimate `answer`, `ask`, and `refuse_unknown` outcomes. The agent may draft and document this representation but cannot establish authority. Unresolved meaning must ask the declared clarification or refuse. Skills with no organizational interpretation declare that this conditional contract does not apply. Read `references/discovery-metadata.md` for the schema. ### Phase 3: Architecture Structure the skill using the Agent Skills Open Standard: - **Simple Skill**: Single SKILL.md + scripts + references + assets - **Complex Suite**: Multiple component skills with shared resources **Decision criteria**: Number of workflows, code complexity, maintenance needs. See `references/architecture-guide.md` for decision logic and directory structures. ### Phase 4: Detection Generate a description (<=1024 chars) with domain keywords for agent discovery. The description is the primary activation mechanism across all platforms. See `references/pipeline-phases.md` for detailed Phase 4 instructions. ### Phase 5: Implementation Create all files in this order: 1. Create directory structure 2. Write **SKILL.md** — starts with `# /skill-name`, includes trigger section with invocation examples, spec-compliant frontmatter 3. Write **AGENTS.md** — companion instruction file for maximum cross-tool reach (~15 tools read AGENTS.md). Contains skill purpose, activation triggers, usage instructions, and a reference to SKILL.md for full details. Follows the AAIF-governed AGENTS.md format 4. Implement Python scripts (functional, no placeholders, no TODOs). **For a multi-script pipeline**, also emit a single `scripts/run_pipeline.py` orchestrator that runs the steps in order and wires output→input **in code** — so the agent runs one command instead of sequencing steps from prose. Skip for genuinely interactive/branching skills. **If any pipeline step invokes an LLM**, follow the LLM-step contract in `references/phase5-orchestration.md`: model id resolved from `--model` argv / `$EVAL_MODEL` env with a pinned default, and runtime-reported usage written to the `{output}.usage.json` sidecar — so `run_evals.py --rollout --model A --model B` can price the task per model. See `references/phase5-orchestration.md` 5. Write references (detailed documentation the skill loads on demand) 6. Write assets (templates, configs) 7. **Emit the eval spec** (skip if `--no-eval`): write `evals/<name>.eval.md` (the binary checks + golden cases derived in Phase 2, one marked `"split": "test"` as the holdout, plus a `judge` block with a pinned model and known-bad canary when any criterion is `llm-judge`) and copy `scripts/run_evals_template.py` → the generated skill's `scripts/run_evals.py`. See `references/phase2-eval-assessment.md` 7.5. Write **`discovery.json`** with the required decision contract (`question`, `trigger`, `decision`, `evidence`, and `success_measure`), plus the real-world outcome, intended users, input types, output artifacts, use cases, invocation examples, permissions/systems, typical completion time, declared platform compatibility, environment discovery/readiness, risk and mutation boundaries, the conditional software-mutation representation review, the conditional structured data-interface contract, the conditional governed semantic contract, positive/negative routing tests, and support tier. Read `references/discovery-metadata.md`. Never generate a skill without the five decision-contract fields; do not invent compatibility certification during creation. If the user has named a target governed marketplace and its published governance configuration identifies the responsible owners and required intake state, also write those exact values as `metadata.owners` and `metadata.approval_status` in `SKILL.md`. Do not guess an owner, approver, department, or approval status when no target marketplace is known; leave organizational assignment to intake. 7.6. Copy the ready **`interview.json`** into the generated skill root. Run `python3 scripts/structured_interview.py gate <skill>/interview.json` immediately before copying it. A blocked state stops generation; never downgrade a confirmed field to a proposal or remove conflicts to pass the gate.