Agent Skill Creator

PR Blocker Summarizer

Turn a JSON export of open pull requests into a blockers-first digest: which PRs are blocked (failing checks, requested changes, or stale), which are ready to merge, and a one-line count an agent can post to standup.

A bundled example skill — small but real, used to demonstrate the creator's validation, pipeline, and eval-rollout machinery.

Activation

Activates on "summarize open PRs", "what's blocking my PRs", "PR standup", "review backlog". Do not activate on general git/GitHub questions unrelated to triaging a set of PRs.

Input

A JSON array of PRs, each with title, state (open), checks (passing/failing), review (approved/changes_requested/pending), and age_days. Missing fields are treated conservatively (counted as not-blocked only when clearly ready).

Run

python3 scripts/run_pipeline.py --input prs.json --output digest.json

Output JSON shape:

{
  "total": 7,
  "blocked": [{"title": "...", "reasons": ["failing checks"]}],
  "ready": ["..."],
  "summary": "7 open · 3 blocked · 2 ready to merge"
}

Anti-goals

• Does not call the GitHub API; it works on an exported PR list.
• Does not merge or comment on PRs; it only summarizes.

What happened A clear description of the bug.

What you ran The exact /agent-skill-creator … prompt or command, and the tool you ran it in (Claude Code, Cursor, Gemini CLI, …).

Expected vs. actual What you expected to happen, and what actually happened (paste output / errors).

Environment

• OS:
• Tool + version:
• Python version (python3 --version):
• agent-skill-creator version / commit:

If a generated skill is involved

• Output of python3 scripts/validate.py <skill>/
• Output of python3 scripts/check_pipeline.py <skill>/

The workflow or capability What do you want to turn into a skill, or what should the creator do that it doesn't yet?

What you'd hand it The input you have (prose, a PDF, a URL, a script, a transcript).

What "good" looks like How would you know the generated skill (or the new capability) worked? A couple of yes/no checks if you can — this maps straight onto the eval spec the creator emits.

Anything you've tried Current workarounds, related skills, prior attempts.

<!-- Thanks for contributing! Keep changes surgical and tests green. -->

What & why What does this change and why? Link any issue (Closes #…).

Type

• [ ] fix
• [ ] feat
• [ ] refactor
• [ ] docs
• [ ] test / chore

Checks

• [ ] uv run pytest scripts/tests/ is green
• [ ] If I touched an install script, I updated its bash/PowerShell counterpart

(test_install_parity.py still passes)

• [ ] If I touched the pipeline/validators, I updated the relevant references/ docs
• [ ] No secrets, no placeholder/stub code in anything that ships

Demo assets

This folder holds the README's visual demo. Two pieces:

• `hero.svg` — a static flow diagram (workflow description → 5-phase pipeline →

17 platforms). Committed, renders on GitHub immediately, linked under the GIF as the conceptual overview / fallback.

• `demo.cast` — an asciinema v2 cast that re-paces the

genuine output of a generated skill's quality gates (validate → security_scan → eval --rollout). Rendered to demo.gif, the README's top visual.

The honesty rule

Every line of output in demo.cast is verbatim real output captured from running the commands below against the bundled example skill (references/examples/weekly-crm-report). Nothing is hand-written or embellished. Only the $ … command prompts and an honest … (5 non-blocking warnings) truncation marker are authored; the timing is paced for readability (these are fast scripts that dump output near-instantly on a real TTY, so a raw real-time capture would just flash). Re-running the commands reproduces the same output.

Render the GIF (one step — needs agg)

agg is the official asciinema GIF generator: <https://github.com/asciinema/agg>

# install agg (pick one)
brew install agg            # macOS
cargo install --git https://github.com/asciinema/agg

# render the committed cast to a GIF (README defaults: small font, idle trimmed)
~/.claude/skills/readme-terminal-gif/scripts/render.sh assets/demo.cast assets/demo.gif
# or, plain agg:
agg --font-size 14 --idle-time-limit 2 --theme asciinema assets/demo.cast assets/demo.gif

Re-build the cast from real output (reproducible)

The cast is built from the verbatim output of three real commands via the readme-terminal-gif skill's replay path:

# 1. capture genuine output
python3 scripts/validate.py references/examples/weekly-crm-report          > /tmp/out_validate.txt 2>&1
python3 scripts/security_scan.py references/examples/weekly-crm-report      > /tmp/out_scan.txt 2>&1
python3 references/examples/weekly-crm-report/scripts/run_evals.py --rollout > /tmp/out_rollout.txt 2>&1

# 2. re-pace it into a cast (storyboard references those files; text stays verbatim)
~/.claude/skills/readme-terminal-gif/scripts/make_cast.py assets/storyboard.json --out assets/demo.cast

# 3. render + eyeball a frame before committing
~/.claude/skills/readme-terminal-gif/scripts/render.sh assets/demo.cast assets/demo.gif
~/.claude/skills/readme-terminal-gif/scripts/check_frame.py assets/demo.gif /tmp/frame.png 1.0

Storyboard (what the cast shows)

A real quality-gate run on a generated skill, ending on the proof beat:

1. $ validate.py …/weekly-crm-report → Status: VALID (+ 5 non-blocking warnings, truncated). 2. $ security_scan.py …/weekly-crm-report → Status: CLEAN — No security issues found. 3. $ run_evals.py --rollout → 9 golden-case checks, all pass → rollout: 9 passed, 0 failed, 0 errored.

That closing line — a generated skill's bundled evals actually passing — is the beat that makes a cold visitor "get it".

Changelog

All notable changes to this project are documented here. The format is based on Keep a Changelog, and this project adheres to semantic versioning where practical.

[Unreleased]

Added

• Launch-readiness pass: rewritten README first screen (working hero visual,

quickstart, "why this vs alternatives" table), assets/hero.svg + assets/demo.cast terminal demo, GitHub Actions CI (/.github/workflows/ci.yml) with a status badge, issue/PR templates, CITATION.cff, two new runnable example skills (weekly-crm-report, pr-blocker-summarizer), and a launch kit (LAUNCH.md + docs/launch/). Corrected the platform count to the real 17 (was overstated as "20+") throughout the README.

• End-to-end eval rollout harness: run_evals.py --rollout runs a skill's

declared run command on each golden input and scores the real output through the existing command checks (closing the "does not run the skill itself" gap). --promote captures the first passing output as the pending-first-green baseline; --timeout bounds each run. The bundled stock-analyzer example now ships a real eval spec + run_pipeline.py so the harness is integration-tested.

• LICENSE (MIT), CONTRIBUTING.md, and this CHANGELOG.md.
• Windows installers tracked in version control (install.ps1,

scripts/bootstrap.ps1, scripts/bootstrap.bat, scripts/install-skill.ps1, scripts/install-template.ps1), with test_install_parity.py gating bash/PowerShell parity.

• Phase 5 harness patterns: every generated skill gets input validation,

--check-prereqs, --diagnostics, self-bootstrapping wrappers, and activation/provenance frontmatter checks in validate.py.

Changed

• Consolidated SKILL.md parsing into scripts/skill_document.py and the

install-target registry into scripts/platforms.py.

• Bumped architecture-guide.md and export-guide.md headers to v6.0.

Removed

• Marketing collateral (Dynamous/) and a one-off research dump

(agentic-tool-skill-systems/).

[6.0.0]

• Five-phase generation pipeline (discovery, design, architecture, detection,

implementation) documented in references/pipeline-phases.md.

• Cross-platform export across 17 agent platforms.
• Per-skill eval specs (evals/*.eval.md + scripts/run_evals.py).
• Deterministic pipeline orchestration (run_pipeline.py) for multi-script

skills.

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or email address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at agrolisboa@gmail.com. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations

Contributing

Thanks for your interest in improving agent-skill-creator. This skill generates cross-platform agent skills, so changes need to keep the generator correct and its tests green.

Workflow

1. Fork the repository and create a feature branch. 2. Make your changes. 3. Add or update tests under scripts/tests/. 4. Run the checks below — they must pass. 5. Open a pull request describing what changed and why.

Local checks

The tooling is stdlib-only Python; tests run with pytest.

# Run the full test suite (must be green)
uv run pytest scripts/tests/

# Validate a skill's SKILL.md against the spec
python3 scripts/validate.py <skill-dir>

# Verify a skill's script pipeline (compiles, deps declared)
python3 scripts/check_pipeline.py <skill-dir>

# Security scan
python3 scripts/security_scan.py <skill-dir>

Conventions

• Commits: conventional commits (feat:, fix:, refactor:, docs:,

test:, chore:).

• Style: PEP 8, type annotations on function signatures, ruff clean.
• Cross-platform parity: the install scripts ship as bash/PowerShell pairs.

When you touch one (install-skill.sh, bootstrap.sh, install-template.sh, install.sh), update its .ps1/.bat counterpart so scripts/tests/test_install_parity.py stays green.

• Single source of truth: SKILL.md parsing lives in scripts/skill_document.py

and the install-target list in scripts/platforms.py — extend those rather than re-implementing parsing or hardcoding platform paths.

Adding a new platform

The most common contribution. A platform addition touches a fixed set of files — change them together or CI's parity tests will catch the drift:

1. `scripts/platforms.py` — add the platform tuple (name, user-level install path, project-level install path, detection directory). This is the single source of truth the registry and installers read. 2. `install.sh` and `install.ps1` — add the detection/install branch to both (bash and PowerShell must stay in lockstep). 3. `scripts/install-template.sh` and `scripts/install-template.ps1` — the installer template bundled into generated skills; mirror the same branch there. 4. Docs — add the platform to the tier table in SKILL.md and references/cross-platform-guide.md. If the platform needs a format adapter (not native SKILL.md), document the transformation in the Tier 2 section. 5. Platform count — the number of supported platforms is stated in README.md, SKILL.md, and references/cross-platform-guide.md. Bump it in all three in the same PR (and remind a maintainer to update the GitHub repo description).

Then verify:

uv run pytest scripts/tests/test_platforms.py scripts/tests/test_install_parity.py

test_platforms.py cross-checks platforms.py against the shell installers, so a partial addition fails loudly.

A note on eval specs

Generated skills bundle run_evals.py (from scripts/run_evals_template.py), which executes spec-defined command checks via the shell. Eval specs are trusted input — only run evals from specs you or your team wrote.

License

By contributing, you agree that your contributions are licensed under the MIT License.

Product Hunt copy

Launch 12:01am PT for a full day on the leaderboard. Have the GIF + 3–4 gallery images ready (hero diagram, demo GIF, an example skill's output, the comparison table). Reply to every comment.

Name

Agent Skill Creator

Tagline (≤60 chars)

Pick one:

• Turn any workflow into a cross-platform agent skill
• Describe a workflow → a validated skill on 17 AI tools
• Agent skills for Claude, Cursor & 15 more — from plain English

Description (≤260 chars)

Describe a workflow in plain English — or hand over a PDF, URL, or script — and get

a complete, validated, security-scanned agent skill that installs on 17 AI coding

tools. Functional code, a built-in eval spec, and a cross-platform installer. MIT.

First comment (maker)

Hi PH 👋 I'm the maker.

>

I kept re-explaining the same workflows to Claude Code and Cursor, and hand-writing

a proper agent skill took hours each time. So I built a generator: you describe what

you do, it runs a deterministic 5-phase pipeline and writes the whole skill — code,

docs, a cross-platform installer, and (the part I'm proud of) its own eval spec, so

every skill is a regression test from day one.

>

It targets 17 tools (Claude Code, Cursor, Copilot, Gemini, Windsurf, Cline, Codex…)

with format adapters so the same skill works everywhere.

>

It's MIT, has runnable examples you can try in one command, and I've been honest in

the README about what it doesn't do (no auto-grading of subjective quality; it's not

magic). Would love your feedback — especially from anyone living in these tools daily.

Topics

Developer Tools · Artificial Intelligence · Open Source · GitHub

Gallery (order)

1. Hero diagram (assets/hero.svg → PNG) 2. Demo GIF (assets/demo.gif) 3. An example skill's output (e.g. weekly-crm-report summary JSON) 4. The "why this vs alternatives" comparison table

Reddit copy

Reddit punishes anything that smells like marketing. Post as a builder sharing a tool, lead with the problem, disclose you're the author, and engage in comments. Read each subreddit's self-promotion rules first; space posts out (don't blast all the same day from one account).

Where (ranked by fit)

• r/ClaudeAI — most on-target (Claude Code / skills audience).
• r/ChatGPTCoding — broad AI-coding tooling crowd.
• r/LocalLLaMA — tooling-savvy; lead with the cross-platform + determinism angle.
• r/cursor, r/github_copilot — niche but high-intent; frame per tool.

Title options

• I built a tool that turns a plain-English workflow into an agent skill that installs on 17 AI tools (Claude Code, Cursor, Copilot…)
• Tired of re-explaining workflows to Claude/Cursor every session — so I made a generator that writes the skill for you (open source)

Body

I use Claude Code and Cursor daily and got tired of re-explaining the same

workflows every session. Writing a proper agent skill by hand means learning the

SKILL.md spec, getting activation right, writing the code, and testing it — a few

hours each time.

>

So I built Agent Skill Creator (MIT, open source). You describe what you do in

plain English — or hand it a PDF / URL / script / transcript — and it runs a

deterministic 5-phase pipeline and writes the whole skill: functional code, docs, a

cross-platform installer for 17 tools, and its own eval spec (binary checks +

golden cases) so the skill is a regression test from the start. `run_evals.py

--rollout` actually runs the skill on the golden inputs and scores the real output.

>

Honest about the limits in the README: it doesn't auto-grade subjective quality

(those checks print as a checklist), the rollout is opt-in (runs arbitrary code),

and it's not magic — a skill is only as good as the workflow you describe.

>

Repo + runnable examples (try one in a single command):

https://github.com/FrancyJGLisboa/agent-skill-creator

>

I'm the author — happy to answer questions or take feature requests. What workflow

would you want to turn into a skill first?

Per-subreddit angle

• r/ClaudeAI: emphasize Claude Code skills + artifacts (charts) + the eval loop.
• r/LocalLLaMA: emphasize 17-platform reach, determinism (run_pipeline.py),

stdlib-only tooling, no lock-in.

• r/ChatGPTCoding: emphasize "stop re-explaining workflows" + cross-tool install.
• r/cursor / r/github_copilot: open on that tool by name; note format adapters.

Rules of engagement

• Always disclose you're the author (mods ban stealth promo).
• Reply to every top comment in the first hour.
• No cross-posting the identical text same-day; tailor the opener per sub.

Show HN copy

HN rewards plain, honest, specific. No marketing voice. Lead with what it does and what's interesting/hard about it. Be in the thread to answer every comment fast.

Title options (pick one; keep it factual)

1. Show HN: Turn any workflow into an agent skill that installs on 17 AI tools 2. Show HN: Agent Skill Creator – describe a workflow, get a validated cross-platform skill 3. Show HN: Generate Claude/Cursor/Copilot agent skills from a plain-English workflow

HN strips emoji and punctuation games. Avoid "magic", "AI-powered", exclamation

marks. The first title is the safest: concrete value + the surprising number.

Body (first comment from the author)

I kept re-explaining the same workflows to Claude Code / Cursor every session, and

writing a proper agent skill by hand meant learning the SKILL.md spec, getting

activation keywords right, writing the code, and testing it — a few hours each time.

>

So I built a generator. You describe what you do in plain English (or hand it a

PDF, a URL, a script, a transcript) and it runs a deterministic 5-phase pipeline:

discovery → design (it derives binary eval criteria) → architecture → activation

detection → build. The output is a complete skill with functional code, a bundled

eval spec, a security scan, and a cross-platform installer that targets 17 tools

(Claude Code, Cursor, Copilot, Gemini, Windsurf, Cline, Codex, …).

>

Two things I think are interesting:

- Every generated skill ships its own metric. It writes an eval spec (binary

checks + golden cases) and a runner, so the skill is a regression test from day

one — and run_evals.py --rollout actually runs the skill on the golden inputs

and scores the real output.

- Determinism over prose. Multi-script skills get a single run_pipeline.py

orchestrator so an agent runs one command instead of sequencing steps from prose

it might misread.

>

Honest limits: it doesn't auto-grade subjective "llm-judge" criteria (those print

as a checklist), the eval rollout is opt-in (it runs arbitrary skill code), and a

generated skill is only as good as the workflow you describe — it surfaces implicit

requirements but it's not magic.

>

Repo (MIT), runnable examples you can try in one command, CI green:

https://github.com/FrancyJGLisboa/agent-skill-creator

>

Happy to answer anything about the pipeline, the cross-platform install, or how the

evals work.

Comment-readiness (have answers ready)

• "Why not just Anthropic's skill-creator?" → it's great for interactive Claude

authoring; this turns existing material into a validated skill that installs everywhere, with test/security gates. (Point to the comparison table.)

• "Does it lock me into Claude?" → no — 17 platforms, format adapters for Cursor

(.mdc), Windsurf, Junie; universal ~/.agents/skills/ path.

• "How do I know the generated code isn't garbage?" → validate + security scan are

hard gates; every skill ships an eval spec; show the example rollout output.

• "What does it cost / need?" → MIT, stdlib Python tooling, git + any one of 17

tools; no API key to get started.

Tweet / X thread

Attach the demo GIF to tweet 1 — the visual carries the thread. Keep each tweet standalone-readable. Replace the link with the canonical repo URL.

---

1/ (hook + GIF) I was re-explaining the same workflows to Claude Code and Cursor every single session.

So I built a thing: describe a workflow in plain English → get a real agent skill that installs on 17 AI tools.

No spec writing. No prompt engineering. No coding.

👇 (15s demo) [attach assets/demo.gif]

2/ You hand it whatever you have — a sentence, a PDF, a runbook URL, an old script, a meeting transcript.

It runs a 5-phase pipeline (discovery → design → architecture → detection → build) and writes the whole skill: code, docs, installer.

3/ The part I actually care about: every generated skill ships its own eval spec.

Binary pass/fail checks + golden cases, written for you. So the skill is a regression test from minute one — and it can run itself on those inputs and score the real output.

4/ And it's genuinely cross-platform. One skill → Claude Code, Cursor, Copilot, Gemini, Windsurf, Cline, Codex, Kiro, Goose, and more (17 total).

Format adapters + a universal install path handle the per-tool differences for you.

5/ (honest limits — builds trust) What it won't do: auto-grade subjective quality (those checks print as a checklist), and it's not magic — a skill is only as good as the workflow you describe. It surfaces the implicit requirements, but you're still the domain expert.

6/ (CTA) MIT-licensed. Runnable examples you can try in one command. CI's green.

If you live in Claude Code / Cursor / Copilot, I'd love your feedback: https://github.com/FrancyJGLisboa/agent-skill-creator

⭐ if it's useful — it genuinely helps.

---

Notes

• Tweet 1 alone should make sense if it's the only one someone sees — the GIF does

the heavy lifting.

• The direct "⭐ if useful" ask is fine on X (unlike HN, where it's not).
• If a high-reach account in the Claude/agent space engages, reply fast and pin the

best reply. One amplifier > many cold posts.

agent-skill-creator v6.0 — Artifacts-First Design

Status: Draft for review Date: 2026-05-27 Author: Francy Lisboa Charuto (brainstormed with Claude) Supersedes: Prior v6 spec drafts focused on five-axis composability

---

1. Mission and positioning

v6 is the first agent skill creator that generates skills which emit interactive React artifacts in Claude Code (with Claude.ai web as a stretch target if the same emission format works there — to be verified). Outside Claude (Cursor, Cline, Codex CLI, Gemini CLI, etc.), skills degrade honestly to formatted markdown.

This is a deliberate scope reduction from the prior v6 drafts. The earlier spec proposed a five-axis composability model with capability registry, contracts, and a custom handoff protocol. Two issues forced a redesign:

1. The handoff protocol (::: visualization named blocks) does not exist in any host. Artifact rendering is a host capability, not a skill capability. Skills emit text; hosts decide what to do with it. 2. If composability is invisible to the user (the UX invariant), the only consumer of the abstraction is the creator's own internals. That is code organization, not a product feature.

The honest scope of v6 is: v4 plus a new Phase 2 step that detects when a skill's output is visualizable and inlines a React artifact emission template into the generated skill.

Headline

"v6 — agent-skill-creator now generates skills that render dashboards in Claude. Other hosts receive formatted markdown."

Specific. Verifiable. Defensible against Anthropic Skills (markdown-only), community creators (no one else does this), and agent frameworks (no React code required from the user).

---

2. UX invariants

These cannot break, or v6.0 does not ship.

• Same command, same UX as v4. /agent-skill-creator <description>

produces an installed skill, with no JSON manifest editing, no axis prefix, no exposed composability concept.

• Cross-platform install path unchanged. install.sh and install.ps1

continue working on macOS, Linux, Windows; the supported hosts list stays at 20+.

• v4 skills keep working. Skills authored under v4 install and execute

under v6 without modification. There is no migration tool because there is no capability registry to migrate.

• Time to install does not regress. A v6 skill creation from prompt to

installed-and-ready is ≤110% of the equivalent v4 timing.

What the user sees that is new

Before: requested "weekly sales report skill," received a skill that produces markdown.

After: requests the same skill, receives a skill that produces markdown plus, when the output is tabular/numeric/spatial and the host is Claude, an interactive React component rendered alongside.

What the user does not see

The Phase 2 artifact assessment step. The inline React template. Any new naming convention. Any new frontmatter fields exposed in the install summary.

---

3. Architecture

3.1 No new abstractions

v6 deliberately does not introduce:

• A capability skill registry separate from the existing skill registry
• An axis prefix system (no dom/, cap/, fmt/)
• A custom handoff protocol with named blocks
• A composition manifest
• Per-skill input/output schemas as a first-class concept

If any of these become necessary later, they can be added in v6. For v6.0, the simplest design that delivers artifact output is the design.

3.2 One new pipeline step

A new step inside Phase 2 (Design), named "Artifact Opportunity Assessment," runs after the domain has been identified and before the SKILL.md is generated.

The step answers two questions:

1. Is this skill's expected output visualizable? (heuristic, see §3.4) 2. If yes, which artifact template fits? (line chart, bar chart, table, KPI cards, or none for v6.0)

If the answer to (1) is yes, the chosen template is inlined into the SKILL.md being generated. The skill's body gets instructions like: "When emitting output, also emit the following React component using Claude's artifact protocol: [inlined template body]."

If the answer to (1) is no, the skill is generated exactly as v4 would have generated it.

3.3 Artifact emission target

v6.0 targets exactly one rendering environment: Claude Code in-chat artifact rendering. The implementation plan must include an explicit verification task to confirm the exact emission format Claude Code expects. This is non-negotiable — the previous spec was blocked on having invented a non-existent protocol.

In hosts that do not render artifacts, the skill's output appears as the markdown analysis followed by a fenced code block containing the React component source. The component itself does not render, but the analysis is still useful. This is "honest degradation."

3.4 Artifact detection heuristic

The detector classifies the expected output of a proposed skill across four signals:

• Tabular signal: does the workflow describe rows × columns of data?

(e.g., "weekly sales report", "inventory by warehouse")

• Temporal signal: does the output describe values over time? (e.g.,

"month over month", "weekly trend")

• Comparative signal: does the output compare entities? (e.g., "by

region", "by salesperson")

• KPI signal: does the output emphasize headline numbers? (e.g.,

"executive dashboard", "key metrics")

These signals are not orthogonal — a "weekly regional sales report" hits tabular + temporal + comparative. The detector picks the template that best matches the dominant combination (line chart for temporal-dominant, bar chart for comparative-dominant, KPI cards for headline-numbers-dominant, table as a baseline when nothing else fits but data is structured).

Implementation: a Python script in scripts/artifact_detector.py that takes the parsed Phase 1 Discovery output as input and returns either None or a template name. Heuristic is keyword-and-pattern-based for v6.0. A learned classifier is not in scope.

3.5 Artifact templates

Four templates ship in v6.0:

• references/artifact-templates/line-chart.jsx — time series
• references/artifact-templates/bar-chart.jsx — categorical comparisons
• references/artifact-templates/kpi-cards.jsx — headline numbers
• references/artifact-templates/data-table.jsx — structured rows (baseline)

Each template uses the same React + recharts (or shadcn for cards/tables) stack that the artifact runtime supports. Templates use placeholder data arrays that the Phase 2 generator replaces with skill-specific instructions on how to populate them.

Templates are inlined into the generated SKILL.md. They do not live as separate installable units. If a user inspects a generated v6 skill, the React template is visible inside the SKILL.md alongside the domain instructions.

---

4. Data flow

4.1 Skill creation flow

1. User invokes: /agent-skill-creator weekly sales report
2. Triage Engine: classifies input (existing v4 logic)
3. Phase 1 Discovery: identifies domain = sales reporting
4. Phase 2 Design:
   4a. (NEW) Artifact Opportunity Assessment
       - Detector reads Phase 1 output
       - Tabular ✓, Temporal ✓, Comparative ✓
       - Picks "bar-chart" as primary template
   4b. Template inlined into draft SKILL.md
   4c. Domain instructions written around the artifact emission
5. Phase 3 Architecture: existing v4 logic
6. Phase 4 Detection: existing v4 logic
7. Phase 5 Implementation:
   - Generate final SKILL.md
   - Run security scan (existing)
   - Validate spec (existing)
   - Install via install-skill.sh (existing — unchanged)
8. User sees: "✓ Skill weekly-sales-report installed"
   (same message as v4)

4.2 Skill invocation flow (Claude Code)

1. User invokes: /weekly-sales-report
2. Skill reads data, performs analysis
3. Skill emits:
   - Markdown analysis text
   - Claude artifact protocol invocation containing the React component
     with the analysis data substituted in
4. Claude Code:
   - Recognizes the artifact protocol
   - Renders the component in-chat
5. User sees: analysis text + rendered chart

4.3 Skill invocation flow (non-Claude host)

1. User invokes: /weekly-sales-report (via Cursor / Cline / Codex / Gemini)
2. Skill reads data, performs analysis
3. Skill emits the same output
4. Host:
   - Does not recognize artifact protocol
   - Displays the artifact tag/block as fenced code (host-dependent)
5. User sees: analysis text + React component source visible as code

This is acceptable. The analysis is still useful. The component source is copy-pasteable into any React environment. The skill does not error.

---

5. Files added and modified

5.1 New files

references/
  phase2-artifact-assessment.md       # When and how to assess artifact fit
  artifact-templates/
    line-chart.jsx
    bar-chart.jsx
    kpi-cards.jsx
    data-table.jsx
scripts/
  artifact_detector.py                # Heuristic classifier

5.2 Modified files

SKILL.md                              # Mention Phase 2 artifact step
references/phase2-design.md           # Document the new step
references/pipeline-phases.md         # Update pipeline diagram and narrative

5.3 Files unchanged

install.sh, install.ps1               # Same install path
scripts/skill_registry.py             # No capability dimension
scripts/validate.py                   # No new validation rules
scripts/security_scan.py              # No changes
references/cross-platform-guide.md    # No new platforms
registry/registry.json                # No schema changes

The diff between v4 and v6 is intentionally small.

---

6. Failure modes and error handling

There is no migration tool because there is no capability registry to migrate. v4 skills run unchanged. There is no install-time interaction required.

---

7. Testing strategy

7.1 Unit tests

scripts/artifact_detector.py requires a labeled dataset:

• 50+ skill descriptions, half visualizable, half not
• Expected template assignment for the visualizable half
• Accuracy threshold: ≥85% correct template assignment

Examples to include in the test set:

• "weekly sales report" → bar-chart or line-chart
• "monthly revenue trend" → line-chart
• "executive KPI dashboard" → kpi-cards
• "inventory by warehouse" → data-table or bar-chart
• "deploy runbook" → None
• "SOX compliance checker" → None
• "Brazil regional crop forecast" → bar-chart or data-table

The 85% threshold is intentionally lower than the originally proposed 90% on 20 examples — a larger sample makes the metric meaningful.

7.2 Integration tests

Generate a fixed set of 5 skills end-to-end (one per template plus one non-visualizable to verify the negative path), install them in a sandbox, invoke them with canned data, and verify:

• Markdown analysis is present
• Artifact emission is syntactically correct for the Claude protocol
• Component source includes the canned data correctly substituted

These tests run without a real LLM in the loop wherever possible (use fixture outputs).

7.3 Regression tests

Critical for the 180+ forks. Select 10 representative v4 skills (the implementation plan picks the specific 10, preferring those exercised in existing examples or referenced in README), install them via v6's install flow, invoke them with canned data, and verify output matches the v4 baseline byte-for-byte (excluding timestamps).

If any v4 skill fails to install under v6, the release blocks.

7.4 Manual verification

Two manual checks required before tagging v6.0:

1. Generate a skill in v6, install it, invoke it in Claude Code, and confirm the artifact renders visually. Capture the screenshot for release notes. 2. Generate the same skill, install it, invoke it in Cursor (or another non-Claude host), and confirm the markdown analysis is useful even without the artifact rendering.

---

8. Success criteria (binary)

All seven must be yes, or v6.0 does not ship.

1. UX preserved. Time from /agent-skill-creator <input> to installed skill is ≤110% of v4 on 20 sample inputs. ✓/✗ 2. v4 forks not broken. Suite of 10 popular v4 skills installs and produces the same output under v6. ✓/✗ 3. Artifact end-to-end works in Claude Code. A v6-generated skill visibly renders a React artifact when invoked. (Manual verification.) ✓/✗ 4. Honest degradation in non-Claude hosts. A v6-generated skill produces useful markdown output in Cursor or Cline. (Manual verification.) ✓/✗ 5. Detector accuracy ≥85%. On 50+ labeled examples. ✓/✗ 6. Cross-platform install works. install.sh on macOS and Linux, install.ps1 on Windows. 20+ supported host claim still validates. ✓/✗ 7. Verification task completed. Implementation plan includes (and completes) an explicit task to confirm Claude Code's exact artifact emission format before inlining templates. ✓/✗

---

9. Non-goals for v6.0

Each of these has been considered and explicitly excluded:

• Multi-host artifact rendering. Cursor, Cline, Codex CLI, Gemini CLI

support beyond text degradation is out. Would require MCP infrastructure or per-host extensions.

• Capability registry. No cap/* skills. No separate registry. Templates

are inlined into domain skills.

• Axis prefix system. No dom/, cap/, fmt/, sty/, val/ namespace.

Naming convention unchanged from v4.

• Custom handoff protocol. No ::: visualization named blocks. Skills

emit text and Claude's existing artifact protocol — nothing else.

• Multi-domain composition. No skills covering two domains.
• Specialization tree. No specialization_of field.
• Parameterized compositions. No composition manifest, parameterized or

otherwise.

• Runtime validation engine. No val/* axis. Validation stays at

generation time (existing v4 logic) plus the artifact assessment.

• Auto-observation. No proactive skill suggestion. User invokes the

creator explicitly.

• Marketplace for third-party templates. Only the four bundled templates

in v6.0. Community templates can be considered in v6.1+.

• Telemetry to refine detection heuristics. Optional follow-up, opt-in,

not blocking v6.0.

If any of these are added later, they become explicit v6.x or v6 work.

---

10. Risks

10.1 Claude artifact protocol changes

The exact emission format for Claude Code artifacts is not documented as a public stable interface. If it changes upstream, the four templates need updates. Mitigation: pin templates to a known-good Claude Code version range in compatibility notes, and treat template maintenance as ongoing work.

10.2 Detector false positives

A skill that should not have a chart gets one anyway. Mitigation: the --no-artifact flag lets the user override. Telemetry-based refinement is a v6.1 concern.

10.3 Marketing claim disputed

"Renders dashboards in Claude" is precise and verifiable. The risk is that competitors counter with "we render too" claims that conflate Claude.ai artifacts with what a skill creator delivers. Mitigation: lead with a video demo, not a feature comparison table.

10.4 Scope creep during implementation

The temptation to bring back the capability registry "while we're at it" will be real. The non-goals list is the answer. v6.0 is deliberately small.

---

11. Open questions

These are unresolved at the design stage and must be answered in or before implementation planning:

• Q1. What is the exact emission format for Claude Code in-chat

artifacts? (Empirical verification required before inlining templates.)

• Q2. Does Claude Code share the artifact protocol with Claude.ai, or

does each have its own variant? If different, do we target both or one?

• Q3. How are the four templates kept in sync if Anthropic changes the

artifact stack (e.g., adds a new sandbox library)? Versioning policy needed.

• Q4. Should v6 emit an artifact when the skill's input data is missing

(the user invokes the skill without data)? Proposal: yes, with placeholder data clearly labeled — the artifact teaches the user what the skill produces. To be confirmed.

---

12. Implementation milestones (handoff to writing-plans)

Suggested decomposition for the implementation plan:

1. M1 — Verify Claude artifact protocol. Empirical task. Generate a minimal skill by hand that emits an artifact in Claude Code. Document the exact emission format. Pin to a known-good Claude Code version. 2. M2 — Build the four templates. Implement line-chart, bar-chart, kpi-cards, data-table as inline-able React components using the verified protocol. 3. M3 — Build the detector. scripts/artifact_detector.py with the 50+ labeled example test set. Hit 85% accuracy. 4. M4 — Wire Phase 2 artifact assessment. Modify pipeline so Phase 2 calls the detector and inlines the chosen template. 5. M5 — Regression test against v4 skills. Suite of 10 popular v4 skills. Confirm no breakage. 6. M6 — Manual end-to-end verification. Generate, install, invoke in Claude Code and in one non-Claude host. Capture artifacts for release notes. 7. M7 — Update docs. SKILL.md, references/, README.

Each milestone is bounded, has a binary completion criterion, and the order is sequential (M1 blocks M2, M3 is independent of M2 but blocks M4, etc.).

---

13. What this design does NOT promise

To be explicit, lest implementation drift back into the prior v6 ambition:

• It does not promise composability as a user-visible feature.
• It does not promise runtime validation.
• It does not promise auto-observation.
• It does not promise five-axis design.
• It does not promise contracts between skills.
• It does not promise a capability marketplace.
• It does not promise rendering in non-Claude hosts beyond honest text

degradation.

These were discussed, judged out of scope for v6.0, and intentionally excluded. If any of them become urgent, they become v6.1, v6, or a separate project.

---

Appendix A: Example generated skill (sketch)

The Phase 2 generator, when artifact assessment chooses bar-chart, would produce a SKILL.md whose body looks roughly like this (simplified):

# /weekly-sales-report

When the user invokes this skill, you will:

1. Read the sales data from the source specified in the user's input.
2. Aggregate revenue by region for the past 7 days.
3. Emit your analysis as markdown:
   - A 2-3 sentence summary of the week
   - Notable changes vs. prior week
   - Anomalies if any
4. Then emit the following artifact using Claude's artifact protocol,
   substituting the aggregated data into the `data` array:

   [INLINED bar-chart.jsx HERE, with a placeholder data array marked
    for substitution]

   The data array should be of the form:
   [{ region: "North", revenue: 12500 }, ...]

The exact protocol invocation syntax is filled in by M1's empirical verification.

---

Appendix B: Why "v6" and not "v4.1"

This change introduces a new category of output (artifacts) and a new pipeline step. It is larger than a patch but smaller than the prior v6 draft. v6.0 still makes sense as a version name because:

• The pipeline gains a new phase step (architectural addition).
• Users see a qualitatively new behavior (rendered charts vs. text only).
• The marketing story is coherent at a major-version level.

If the scope grows during implementation to include any of the deferred non-goals, the version remains v6; if scope shrinks to something less than this design, it becomes v4.1.

---

Appendix C: Decisions explicitly reversed from prior v6 drafts

For audit clarity, these decisions changed during this brainstorm:

• Reversed: "Composability as foundation, three features on top."

Reason: invisible composability is just internal code organization, per advisor review. Adopted instead: no composability abstraction at all.

• Reversed: "Five-axis model with dom/, cap/, fmt/, sty/, val/ prefixes."

Reason: same as above. Adopted instead: no axis system.

• Reversed: "Custom ::: visualization handoff protocol."

Reason: this protocol does not exist in any host; skills cannot invent rendering. Adopted instead: target Claude's actual artifact protocol with empirical verification.

• Reversed: "Cross-platform 20+ with artifacts."

Reason: most of the 20 hosts do not render artifacts. Adopted instead: "Claude-native + honest degradation."

• Confirmed: UX invariant — zero visible composability for the common

user. v4's single-command experience preserved.

v6.0 Test Suite Summary — 2026-05-27

Final test counts

• Template structure tests: 14
• Detector unit tests: 21
• Detector accuracy gate: 1 (passing at 92.0%)
• Phase 2 integration tests: 5
• v4 regression tests: 2
• Total: 43 tests, all passing

Detector accuracy

• Accuracy on labeled set: 92.0% (46/50)
• Threshold required by spec: 85%
• Headroom above threshold: 7.0 percentage points

v4 regression

• v4 skills tested: 10 fixture entries (1 real + 9 synthetic)
• Real-path skills validated: 1/1 — references/examples/stock-analyzer/SKILL.md validates with valid=True under the v6 validator. (Warnings on missing -skill suffix, license, metadata, and AGENTS.md are non-blocking and expected for v4-era skills.)
• Detector did not crash on any v4 description; all 10 returned a value in the allowed set {line-chart, bar-chart, kpi-cards, data-table, None}.

Notes

• The repo ships only one concrete v4 SKILL.md (stock-analyzer). The other 9 fixture entries are synthetic descriptions modelled after README-documented community skills (sales-report-skill, deploy-checklist-skill, quarterly-compliance-skill, customer-churn-skill, incident-runbook-skill) plus four common workflow archetypes (invoice processor, meeting notes, API doc generator, data cleaner). They exercise the detector's no-crash contract against v4-era workflow language.
• Running uv run python -m unittest discover scripts/tests -v produces Ran 43 tests in 0.011s — OK.

Spec coverage audit (2026-05-27)

All spec sections traced to a plan task. No gaps found.

Outstanding for human action

Spec §3.3 (artifact emission target), §4.2-4.3 (invocation flows), §7.4 (manual verification), §8 SC3, SC4, SC7, §10.1, §11 Q1-Q3, and §12 M1 all depend on Tasks 1, 19, 20, which require manual execution by a human (open Claude Code, capture artifact format, verify rendering in Claude Code and a non-Claude host). Plan and code are otherwise complete.

Findings

• No spec gaps found. Every section of the spec maps to at least one

task in the plan.

• **Q4 (artifact with placeholder data) was answered in implementation,

not the manual verification milestone.* The four templates contain intentional placeholder data immediately after the `/ AGENT_SKILL_DATA */ marker, which is rendered when the skill is invoked without input data. Documented in references/templates-guide.md` "Substitution marker" section (Task 21).

• All seven success criteria are either ✓ at code level or explicitly

pending Tasks 1/19/20 (manual). No success criterion is unaddressed.

Launch playbook

A practical, honest guide to launching agent-skill-creator. Copy for each channel is in `docs/launch/`.

The honest part first

Stars are a launch + virality outcome, not an engineering one. A polished repo is the floor — necessary, not sufficient. Repos that hit 10K stars in weeks almost always have a front-page moment: Hacker News front page, a high-reach tweet, a Product Hunt #1, or a big newsletter/creator pickup — sitting on top of a product whose value is obvious in ~30 seconds.

This repo is now built to convert attention at a high rate (clear value above the fold, a working visual, honest positioning, runnable examples, green CI). What it cannot do by itself is manufacture the attention. That part is distribution, and it's yours to drive. The single biggest lever is one amplified push on a channel where the value lands cold — not incremental README tweaks.

Realistic framing: "10K in a month" requires a front-page hit and sustained follow-through. Treat that as the stretch goal. The controllable goal is: ship a launch good enough that if it gets seen, it converts — then maximize shots on goal.

The conversion checklist (already done — verify before launch)

• [ ] First screen: tagline + working visual + one-liner install, no broken images.
• [ ] A 15-second demo (render assets/demo.cast → assets/demo.gif, see

`assets/DEMO.md`) — do this before launch; motion converts.

• [ ] "Why this vs alternatives" table is visible and honest.
• [ ] ≥3 runnable examples a visitor can try in one command.
• [ ] CI badge is green on main.
• [ ] Repo description + topics set on GitHub (see below).
• [ ] Tag matches the README version (v6.0.0).

GitHub setup (do once, before launch)

• Description: "Turn any workflow into a validated agent skill that installs on

17 AI coding tools — no spec writing, no coding."

• Topics: agent-skills, claude, claude-code, llm, ai-agents,

developer-tools, cursor, copilot, cross-platform, mcp.

• Social preview image: upload a PNG of assets/hero.svg

(Settings → Social preview) so shared links render a card, not a generic icon.

• Pin the repo on your profile; enable Discussions.

Sequencing (a sane order)

1. T‑minus days: render the demo GIF, set description/topics/social preview, confirm CI is green, tag v6.0.0. Line up 3–5 people who'll genuinely engage in the first hour (comments/upvotes from real users, not vote rings). 2. Launch day, morning (US Pacific): post Show HN (title options in `docs/launch/show-hn.md`). HN rewards a plain, honest title and an author who answers every comment fast. Be present for 3–4 hours. 3. Same morning: fire the tweet thread (`docs/launch/tweet-thread.md`) with the GIF; ask your network to amplify. Tag relevant accounts only where genuinely relevant. 4. +1 day (if HN went well): Product Hunt (`docs/launch/product-hunt.md`) and the targeted subreddits (`docs/launch/reddit.md`). Don't blast all channels at once — stagger so each gets a real first-hour push. 5. Follow-through: turn the best HN/Reddit questions into README FAQ entries and issues. Momentum compounds when newcomers see an active maintainer.

What actually moves the needle (ranked)

1. A demo that makes the value obvious in one glance. Render the GIF. 2. Showing up. On HN/Reddit, fast, non-defensive author replies often matter more than the post itself. 3. A title that states the value, not the cleverness. "Show HN: Turn any workflow into an agent skill that installs on 17 AI tools" beats anything cute. 4. One credible amplifier. A single retweet from someone with reach in the Claude/agent space outperforms 50 cold posts. 5. Proof it's real. Runnable examples + green CI + honest limits → trust → stars.

What to avoid

• Vote/star rings or asking for stars directly on HN — it backfires and risks bans.
• Overclaiming ("10x", "magic", inflated tool counts). The repo says **17

platforms** because that's the real number; keep every claim true.

• Launching all channels simultaneously, or launching before the GIF exists.
• Going quiet after posting. Silence in the first hour kills threads.

Project learnings — agent-skill-creator

When adding a new Phase-5 gate, also touch the AGENTS.md Files block and the Step-10 report template

When introducing a new Phase-5 verifier, artifact, or generated file (eval spec, pipeline orchestrator, etc.), update two recurring spots in references/pipeline-phases.md that are easy to miss:

• Step 2.5 — the AGENTS.md template's ## Files block. Tools that read

AGENTS.md but not SKILL.md (Augment, Continue.dev, Zed, etc.) only see the file listing here. A missing entry means an incomplete view for those tools.

• Step 10 — the "Report Results" template. Add a Pass: PASSED line for

the new gate so the agent's final summary reflects every check it ran.

Why: missed on the eval feature (caught by review) and again on the orchestration feature (caught by review — same blind spot). The obvious touchpoints — SKILL.md output-structure block, pipeline-phases.md file-order table, the Phase 5 checklist — were handled both times; these two are secondary mirrors of the same information and are silently incomplete unless you remember them.

When to apply: any change that adds a generated file, validator, or Phase-5 step. Treat as a checklist item before declaring a Phase-5 feature done. Quick grep: grep -n "## Files\|Report Results\|Validation: PASSED" references/pipeline-phases.md.

Agent Skill Creator

Turn any workflow into reusable AI agent software that installs on 17 platforms — no spec writing, no prompt engineering, no coding required.

   ![Version]() ![License: MIT]()

<p align="center"> <img src="assets/demo.gif" alt="A real run of a generated skill's quality gates: validate → security scan → eval rollout, all passing." width="820"> </p>

<!-- demo.gif is built from assets/demo.cast (see assets/DEMO.md). hero.svg is the static flow diagram, linked below as the conceptual overview / fallback. --> <p align="center"><em>Genuine output from a real run — <code>validate</code> → <code>security_scan</code> → eval <code>--rollout</code> on a generated skill (paced for readability). <a href="assets/hero.svg">See the flow diagram</a>.</em></p>

What you get: describe a workflow in plain English (or hand over a PDF, a link, a script) → a complete, validated and security-scanned agent skill, with functional code, its own eval spec, and a cross-platform installer → the same skill running on Claude Code, Cursor, Copilot, Gemini, Windsurf, and 12 more with one command.

---

Quick start

# macOS / Linux — paste into Terminal
curl -fsSL https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.sh | sh

Then open your AI tool and describe what you do:

/agent-skill-creator Every Friday I clean the CRM export, calculate regional
totals, and email a PDF sales report.

…and watch it build the skill end to end:

▸ Phase 1  Discovery     ▸ Phase 4  Detection
▸ Phase 2  Design+evals   ▸ Phase 5  Build · validate · security-scan
▸ Phase 3  Architecture

✓ weekly-crm-report-skill  (12 files, evals, installer)
  installed on Claude Code, Cursor, Gemini CLI

Use it:  /weekly-crm-report-skill data/crm-export.csv
  → report.pdf   → dashboard.html

No clone, no pip, no API key to get started — just git and any one of 17 supported tools. Windows one-liners and single-tool installs are in Advanced Install.

---

Why this vs. the alternatives

Anthropic's skill-creator is excellent for authoring a Claude skill interactively. This is for turning whatever you already have into a validated skill that installs everywhere, with the testing and security gates wired in.

---

Examples

Three runnable example skills ship in `references/examples/`. Each one passes the same gates the creator applies to your skills — validate.py, check_pipeline.py, and its own bundled eval spec (run_evals.py --rollout):

Try one without installing anything:

git clone https://github.com/FrancyJGLisboa/agent-skill-creator
cd agent-skill-creator/references/examples/weekly-crm-report
python3 scripts/run_pipeline.py --input evals/golden/case-1/input.csv --output /tmp/summary.json
python3 scripts/run_evals.py --rollout      # runs the skill on its golden inputs and scores them

---

The Problem

Every AI coding tool — Claude Code, GitHub Copilot, Cursor, Windsurf, Codex, Gemini, Kiro, and more — starts from zero. It doesn't know your company's processes, data sources, or compliance requirements. So every person re-explains the same workflows in every conversation. Knowledge stays in individual chat histories. New hires start from scratch.

Agent skills fix this. A skill is structured knowledge your agent loads automatically — like installing an app. Once installed, anyone on your team can invoke it and get consistent results, every time, on any platform.

The catch: building a proper skill requires understanding the spec format, writing clear prompt instructions, designing how information loads progressively, writing functional code, and getting activation keywords right. Even simple skills take multiple rounds of iteration to get right.

Agent Skill Creator removes that barrier entirely. You pass in whatever you have — messy docs, links, code, PDFs, transcripts, vague descriptions — and it produces a validated, security-scanned skill ready to install on 17 platforms and share with your team. You describe what you do; it builds the software.

---

Install & first skill — in detail

1. Install

The macOS/Linux one-liner is in Quick start above. Windows:

Windows (PowerShell):

irm https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.ps1 | iex

Windows (Command Prompt):

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/FrancyJGLisboa/agent-skill-creator/main/scripts/bootstrap.ps1 | iex"

The installer clones to ~/.agents/skills/agent-skill-creator and links to every detected platform (Claude Code, Copilot, Gemini CLI, Kiro, Cline, Roo Code, Kilo Code, Factory Droid, Cursor, Goose, OpenCode). To update later, run cd ~/.agents/skills/agent-skill-creator && git pull.

Advanced: Want to install to a single tool, or already have a local clone? See Advanced Install below.

2. Use it

Open your agent and type /agent-skill-creator followed by whatever you have:

/agent-skill-creator Every week I pull sales data from our CRM, clean
duplicate entries, calculate regional totals, and generate a PDF report.

You can pass anything — plain English, documentation links, existing code, API docs, PDFs, database schemas, transcripts. Combine multiple sources in one message. The more context, the better the result.

/agent-skill-creator Based on our deployment runbook: https://wiki.internal/deploy-process

/agent-skill-creator See scripts/invoice_processor.py — turn it into a reusable skill

3. What comes out

A complete skill, automatically installed on your platform:

Skill installed successfully.

To use it, open a new session and type:

  /sales-report-skill Generate the weekly report for the West region

Installed at: ~/.claude/skills/sales-report-skill

The agent detects your platform, installs the skill to the right location, and tells you exactly how to invoke it. No manual steps.

The generated skill includes a cross-platform installer (install.sh) that auto-detects all 17 supported platforms, generates format adapters for Cursor (.mdc), Windsurf (.md rules), and Junie (guidelines.md) automatically, and creates a universal ~/.agents/skills/ symlink so the skill is discoverable by multiple tools at once.

sales-report-skill/
├── SKILL.md          # Skill definition (activates with /sales-report-skill)
├── AGENTS.md         # Companion file (read by many tools for cross-tool reach)
├── scripts/          # Functional Python code
├── references/       # Detailed documentation
├── assets/           # Templates, configs
├── install.sh        # Cross-platform installer (17 platforms, format adapters, --all flag)
└── README.md         # Installation instructions

Your team installs it the same way — one git clone to their tool's path — and invokes it with /sales-report-skill.

---

What's new

v6 — Artifacts. Skills can emit interactive React artifacts in Claude Code (and Claude.ai). When output is visualizable — time series, comparisons, KPIs, tables — Phase 2 inlines one of four bundled React templates plus the artifact protocol into the generated SKILL.md; you write no React. In hosts that don't render artifacts (Cursor, Cline, Codex CLI, Gemini CLI) the source appears as fenced code and the markdown analysis is unchanged — honest degradation. Suppress with --no-artifact; force a template with --artifact <line-chart|bar-chart|kpi-cards|data-table>. (design notes)

Every skill ships its own metric. Each generated skill carries an eval spec (evals/<name>.eval.md) plus a scripts/run_evals.py runner. In Phase 2 the creator derives 3–6 binary checks and ≥3 golden cases (seeded from your own files); you give a one-word thumbs-up. It's an instant regression test — python3 scripts/run_evals.py exits non-zero on failure, so it drops into CI. With a declared run command, run_evals.py --rollout executes the skill on each golden input and scores the real output (--rollout --promote captures the first passing baseline). The spec is consumable by autoresearch-universal for optimization with no reformatting. Honest limits: --rollout is opt-in (it runs arbitrary skill code), and llm-judge checks print as a checklist rather than being auto-graded. On by default; skip with --no-eval.

---

How It Works

You don't need to understand any of this to use it. But if you're curious:

The agent doesn't just follow your description literally. Humans describe what they do, not what they need. "I pull sales data and make a report" hides a dozen implicit requirements — who reads the report, what format, what happens when data is missing. The agent reads all your material, uncovers these implicit requirements, and generates its own internal specification before writing any code. It builds from that deeper understanding, not from your surface description.

UNDERSTAND    Read all material → uncover real intent → generate internal spec
BUILD         Structure directory → write code and docs → craft activation keywords
VERIFY        Spec validation → security scan → block delivery if either fails

Every skill is automatically validated (correct structure, naming, metadata) and security-scanned (no hardcoded keys, no credential exposure, no injection risks) before delivery. Skills that fail these checks are blocked.

---

Share Skills Across Your Team

After the agent builds and installs your skill, it asks:

Want to share this skill with your team so they can install it too?

Say yes. The agent detects whether your team uses GitHub or GitLab, creates a repo, pushes the skill, and gives you a one-liner to share:

Shared! Your colleagues can install it by pasting this in their terminal:

  git clone https://github.com/your-org/sales-report-skill.git ~/.agents/skills/sales-report-skill

One git clone to ~/.agents/skills/ makes it available on Codex CLI, Gemini CLI, Kiro, and Antigravity simultaneously. For Claude Code users: ~/.claude/skills/sales-report-skill. For Cursor: .cursor/rules/sales-report-skill.

Send that line to your colleague on Slack or Teams. They paste it. Done. They can now type /sales-report-skill in their agent.

No registry commands, no publishing steps, no terminal knowledge beyond paste. The agent handles the repo creation, the push, and generates install commands for every platform.

The result over time

Each team member creates skills from their own domain and shares them. Over months the organization accumulates a library of reusable skills:

• Sales team shares /sales-report-skill
• Engineering shares /deploy-checklist-skill
• Legal shares /quarterly-compliance-skill
• Data science shares /customer-churn-skill
• SRE shares /incident-runbook-skill

Any colleague installs any skill with one git clone. Any agent on any platform can invoke it. Knowledge compounds instead of evaporating.

For teams and consultants: the skill registry

When an organization has more than a few skills, the agent offers to set up a team skill registry — a shared git repo where all team members publish their skills and anyone can browse and install them.

The consultant (or team lead) sets it up once:

python3 scripts/skill_registry.py init --name "Acme Corp Skills"

Then every team member can:

# Publish a skill they created
python3 scripts/skill_registry.py publish ./sales-report-skill/ --tags sales,reports

# Browse what's available
python3 scripts/skill_registry.py list

# Search for a specific skill
python3 scripts/skill_registry.py search "sales"

# Install a colleague's skill (auto-detects platform)
python3 scripts/skill_registry.py install sales-report-skill

The registry is a git repo on GitHub or GitLab. Clone it once, and every team member can publish and install. No servers, no databases — just git.

For AI consultants: The engagement model is teach, not build. Install agent-skill-creator on each team member's machine, create the shared {team}-skills-registry repo, teach the team the 5-step workflow (install, clone registry, create skill, publish, install from registry), and hand over a self-sustaining system. After you leave, the team keeps creating and sharing skills on their own. They know their workflows better than you do — your job is to remove the friction.

---

Advanced Install

If you prefer to install to a single tool, or you already cloned the repo:

Clone to a specific tool:

# Claude Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.claude/skills/agent-skill-creator

# GitHub Copilot
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.copilot/skills/agent-skill-creator

# Gemini CLI
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.gemini/skills/agent-skill-creator

# Cursor (per-project — no global path)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .cursor/skills/agent-skill-creator

# Universal path (Codex CLI, OpenCode, Goose, and others)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.agents/skills/agent-skill-creator

Already cloned? Link to all tools:

macOS / Linux:

cd agent-skill-creator
./install.sh              # Link to all detected platforms
./install.sh --dry-run    # Preview without changes
./install.sh --uninstall  # Remove all links

Windows (PowerShell):

cd agent-skill-creator
.\install.ps1              # Link to all detected platforms
.\install.ps1 -DryRun     # Preview without changes
.\install.ps1 -Uninstall  # Remove all links

See the full platform table below for every supported tool and path.

---

All Platforms

17 platforms supported. Same skill, same invocation, same results everywhere.

How it works

Every generated skill outputs both SKILL.md (~15 tools read it natively) and AGENTS.md (~15 tools read it) to maximize reach. Tools in Tier 2 need format conversion — the installer handles it automatically.

Global install (each tool's native path)

# Claude Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.claude/skills/agent-skill-creator

# GitHub Copilot
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.copilot/skills/agent-skill-creator

# Gemini CLI
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.gemini/skills/agent-skill-creator

# Kiro
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.kiro/skills/agent-skill-creator

# Cline
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.cline/skills/agent-skill-creator

# Roo Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.roo/skills/agent-skill-creator

# Kilo Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.kilocode/skills/agent-skill-creator

# Factory Droid
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.factory/skills/agent-skill-creator

# Goose
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.config/goose/skills/agent-skill-creator

# OpenCode
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.config/opencode/skills/agent-skill-creator

# Codex CLI / universal path (read by 7+ tools as fallback)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.agents/skills/agent-skill-creator

Use each tool's own native path. The universal ~/.agents/skills/ path works as a fallback for Codex CLI, Gemini CLI, OpenCode, Goose, Cline, Roo Code, and Kilo Code.

Per-project install

# GitHub Copilot
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .github/skills/agent-skill-creator

# Cursor (project only — no global path exists)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .cursor/skills/agent-skill-creator

# Windsurf
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .windsurf/rules/agent-skill-creator

# Cline
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .clinerules/skills/agent-skill-creator

# Kiro
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .kiro/skills/agent-skill-creator

# Trae
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .trae/rules/agent-skill-creator

# Roo Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .roo/skills/agent-skill-creator

# Kilo Code
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .kilocode/skills/agent-skill-creator

# Junie (JetBrains)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .junie/skills/agent-skill-creator

# Antigravity (note: .agent/ singular, NOT .agents/)
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .agent/skills/agent-skill-creator

Cursor — global workaround

Cursor has no global skills directory. Clone once and symlink per project:

# 1. Clone once
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/agent-skills/agent-skill-creator

# 2. In any project, symlink
mkdir -p .cursor/rules && ln -s ~/agent-skills/agent-skill-creator .cursor/rules/agent-skill-creator

Add a shell alias to automate this (~/.zshrc or ~/.bashrc):

alias install-skills='mkdir -p .cursor/rules && ln -s ~/agent-skills/agent-skill-creator .cursor/rules/agent-skill-creator'

Then in any project: install-skills. Updates propagate automatically via the symlink.

Using the installer (for generated skills)

Every skill generated by agent-skill-creator includes a cross-platform installer — both install.sh (macOS/Linux) and install.ps1 (Windows):

macOS / Linux:

./install.sh                          # Auto-detect platform
./install.sh --platform cursor        # Force specific platform (auto-generates .mdc)
./install.sh --all                    # Install to every detected tool at once
./install.sh --dry-run                # Preview without installing

Windows (PowerShell):

.\install.ps1                          # Auto-detect platform
.\install.ps1 -Platform cursor         # Force specific platform
.\install.ps1 -All                     # Install to every detected tool at once
.\install.ps1 -DryRun                  # Preview without installing

Both installers handle all 17 platforms and create a universal ~/.agents/skills/ link after every install for cross-tool discoverability.

Claude Desktop / claude.ai

python3 scripts/export_utils.py ./agent-skill-creator/ --variant desktop
# Then: Settings > Skills > Upload the generated .zip

Update

cd ~/.agents/skills/agent-skill-creator && git pull

If you used the one-liner (Option A) or ./install.sh (Option C), all symlinks update automatically — just git pull once from the canonical location. The skill also performs a silent git-based version check when loaded and will mention if a newer version is available.

---

Quality Gates

Every skill goes through automated checks before delivery and on every publish:

Run them independently anytime:

python3 scripts/validate.py ./my-skill/
python3 scripts/security_scan.py ./my-skill/
python3 scripts/staleness_check.py ./my-skill/
python3 scripts/staleness_check.py ./my-skill/ --check-deps --check-drift

Skills that fail validation cannot be published. On publish, high-severity security issues block the skill (override with --force). On export, findings are reported but don't block by default — pass --strict to fail the export on any high-severity issue.

---

Staleness Detection

Skills go stale. APIs change, compliance rules update, data sources move. A skill that worked six months ago may silently produce wrong results today. Staleness detection surfaces this before users hit it.

Three layers, each opt-in:

Review tracking — Every skill can declare when it was last reviewed and how often it should be. The staleness checker compares these dates and flags overdue skills. Skills without explicit dates fall back to the last git commit date on SKILL.md.

python3 scripts/staleness_check.py ./my-skill/
# Exit code 0 = fresh, 1 = overdue for review

Dependency health — Skills can declare external URLs they depend on (APIs, data sources). The --check-deps flag HTTP-checks each one and reports failures.

python3 scripts/staleness_check.py ./my-skill/ --check-deps
# Exit code 2 = one or more dependencies unreachable

Schema drift — Skills can declare the expected top-level keys in API responses. The --check-drift flag fetches each endpoint and compares actual keys against expected. Missing keys = the API changed under you.

python3 scripts/staleness_check.py ./my-skill/ --check-drift

All three layers are controlled by optional frontmatter fields. Existing skills work unchanged — the tool just suggests adding the metadata:

metadata:
  created: 2026-02-27
  last_reviewed: 2026-02-27
  review_interval_days: 90
  dependencies:
    - url: https://api.example.com/v1
      name: Example API
      type: api
  schema_expectations:
    - url: https://api.example.com/v1/data
      method: GET
      expected_keys:
        - id
        - price
        - volume

For teams using the skill registry, stale scans every published skill at once:

python3 scripts/skill_registry.py stale
# NAME            VERSION  STATUS   DAYS SINCE  SOURCE          INTERVAL
# sales-report    1.2.0    OVERDUE  127         last_reviewed   90
# deploy-check    2.0.1    FRESH    12          published       90

---

Tools Reference

Registry Commands

python3 scripts/skill_registry.py init --name "Acme Corp Skills"     # First-time setup
python3 scripts/skill_registry.py publish ./skill/ --tags t1,t2      # Publish a skill
python3 scripts/skill_registry.py list                                # Browse all skills
python3 scripts/skill_registry.py search "query"                     # Search skills
python3 scripts/skill_registry.py info skill-name                    # Skill details
python3 scripts/skill_registry.py install skill-name                 # Install a skill
python3 scripts/skill_registry.py install skill-name --author alice  # Disambiguate a shared name
python3 scripts/skill_registry.py remove skill-name --force          # Remove a skill
python3 scripts/skill_registry.py stale                              # Report stale skills
python3 scripts/skill_registry.py stale --json                       # Machine-readable output

Validation, Security, and Staleness

python3 scripts/validate.py ./skill/               # Spec compliance
python3 scripts/validate.py ./skill/ --json         # Machine-readable output
python3 scripts/security_scan.py ./skill/           # Security audit
python3 scripts/security_scan.py ./skill/ --json    # Machine-readable output
python3 scripts/staleness_check.py ./skill/                      # Review staleness
python3 scripts/staleness_check.py ./skill/ --check-deps         # + dependency health
python3 scripts/staleness_check.py ./skill/ --check-drift        # + schema drift
python3 scripts/staleness_check.py ./skill/ --json               # Machine-readable output

Install Any Skill (Universal Installer)

macOS / Linux:

# From git URL
./scripts/install-skill.sh https://github.com/someone/sales-report-skill.git

# From local path
./scripts/install-skill.sh ./sales-report-skill

# To a specific platform only
./scripts/install-skill.sh ./sales-report-skill --platform cursor --project

# Preview / remove
./scripts/install-skill.sh ./sales-report-skill --dry-run
./scripts/install-skill.sh ./sales-report-skill --uninstall

Windows (PowerShell):

# From git URL
.\scripts\install-skill.ps1 https://github.com/someone/sales-report-skill.git

# From local path
.\scripts\install-skill.ps1 .\sales-report-skill

# To a specific platform only
.\scripts\install-skill.ps1 .\sales-report-skill -Platform cursor -Project

# Preview / remove
.\scripts\install-skill.ps1 .\sales-report-skill -DryRun
.\scripts\install-skill.ps1 .\sales-report-skill -Uninstall

Export

python3 scripts/export_utils.py ./skill/ --variant desktop    # For Claude Desktop
python3 scripts/export_utils.py ./skill/ --variant api        # For Claude API
python3 scripts/export_utils.py ./skill/ --strict             # Block export on high-severity findings

All commands use exit code 0 for success, 1 for errors. All support --json for CI/CD integration.

---

Troubleshooting

Skill not activating: Check that the SKILL.md description field contains keywords matching your query. The description is how the agent decides when to activate the skill.

Validation fails on name: Names must be lowercase, use hyphens between words, 1-64 characters. Examples: sales-report-skill, deploy-checklist.

SKILL.md too long: Move detailed content to references/ files and link from the main SKILL.md.

Platform not auto-detected: Use --platform cursor (or copilot, windsurf, codex, gemini, kiro, trae, goose, opencode, roo-code, kilo-code, factory, junie, cline, antigravity, universal) to specify explicitly.

Install to all tools at once: Inside a generated skill, use ./install.sh --all (macOS/Linux) or .\install.ps1 -All (Windows) to install to every detected platform in one command.

---

Project Structure

agent-skill-creator/
  SKILL.md                      # The skill definition (what the agent reads)
  README.md                     # This file
  CONTRIBUTING.md               # How to contribute (incl. adding a platform)
  CODE_OF_CONDUCT.md            # Contributor Covenant
  CHANGELOG.md                  # Version history
  LICENSE                       # MIT
  install.sh / install.ps1      # Self-installer for cloned repos (macOS/Linux, Windows)
  scripts/
    bootstrap.sh / .ps1 / .bat  # One-liner bootstrap (macOS/Linux, PowerShell, cmd)
    install-skill.sh / .ps1     # Universal skill installer
    install-template.sh / .ps1  # Template for generated skills' installers
    platforms.py                # Canonical 17-platform registry (single source of truth)
    validate.py                 # SKILL.md spec compliance checker
    security_scan.py            # Secret / injection scanner
    check_pipeline.py           # Verifies generated scripts compile + declare deps
    export_utils.py             # Cross-platform export (desktop / API packages)
    skill_registry.py           # Git-based team skill registry
    skill_document.py           # SKILL.md parser (shared by the tools above)
    run_evals_template.py       # Eval runner bundled into generated skills
    staleness_check.py          # Staleness: review dates, deps, schema drift
    dependency_health.py        # API dependency reachability check
    schema_drift.py             # API schema drift detection
    review_staleness.py         # Review-date staleness logic
    artifact_detector.py        # Picks a React artifact shape for a skill
    tests/                      # pytest suite (CI runs this)
  references/                   # Detailed docs (loaded by the agent on demand)
    pipeline-phases.md          # Full 5-phase creation pipeline
    architecture-guide.md       # Skill structure decisions
    quality-standards.md        # Code and documentation standards
    multi-agent-guide.md        # Multi-skill suite creation
    cross-platform-guide.md     # Platform compatibility (tiers, adapters, paths)
    export-guide.md             # Export documentation
    templates-guide.md          # Template system (blueprints)
    interactive-mode.md         # Interactive wizard
    agentdb-integration.md      # Learning system
    phase2-eval-assessment.md      # Eval-spec design reference
    phase2-artifact-assessment.md  # Artifact-detection reference
    phase4-detection.md         # Detection & keyword-design craft reference
    phase5-orchestration.md     # run_pipeline.py orchestration reference
    claude-artifact-format.md   # Artifact emission protocol
    artifact-templates/         # React artifact templates
    templates/                  # Skill templates (activation README template)
    examples/                   # Three runnable example skills
      weekly-crm-report/
      pr-blocker-summarizer/
      stock-analyzer/
  registry/                     # Shared skill catalog
    registry.json
    skills/
  exports/                      # Export output

---

Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, local checks, and a step-by-step guide to adding a new platform. By participating you agree to the Code of Conduct.

The short version: fork, branch, make your change, run uv run pytest scripts/tests/ plus python3 scripts/validate.py ./ and python3 scripts/security_scan.py ./, then open a PR.

---

License

MIT

---

Links

• Agent Skills Open Standard
• What are Claude Skills? (video)
• Cross-Platform Guide
• Architecture Guide
• Pipeline Phases
• Export Guide

AgentDB Integration

Overview

AgentDB is an invisible learning system that improves skill creation quality over time. It operates behind the scenes during every skill creation episode, recording decisions, outcomes, and patterns. The user never interacts with AgentDB directly -- they simply get progressively better skill outputs as the system accumulates experience.

Key principle: AgentDB is always optional. The skill creator works identically with or without AgentDB installed. When available, it provides enhanced intelligence. When absent, the system falls back to its standard pipeline with zero degradation.

What AgentDB Does

AgentDB provides three learning mechanisms:

Reflexion Memory

Stores complete creation episodes (what was attempted, what worked, what failed) and retrieves relevant past experiences when facing similar tasks.

• After creating a financial analysis skill, AgentDB remembers which API scored highest, which analysis patterns the user liked, and which configurations caused issues.
• The next time someone requests a financial skill, the system retrieves these episodes and uses them to make better Phase 1 and Phase 2 decisions.

Causal Reasoning

Tracks cause-and-effect relationships between creation decisions and outcomes.

• "Using Alpha Vantage with rate limiting causes 23% fewer API errors than without"
• "Including a comprehensive report function causes 40% higher user satisfaction"
• These causal links accumulate over time and influence template selection and configuration defaults.

Skill Extraction

Identifies reusable patterns from successful creations and stores them as transferable skills.

• A caching strategy that worked well for NOAA data gets extracted and applied to other API-heavy skills.
• A report generation pattern that received positive feedback gets promoted to a template default.

Integration Points in the 5-Phase Pipeline

AgentDB hooks into each phase of the creation pipeline transparently.

Phase 1: Discovery

Without AgentDB: System researches APIs via WebSearch, compares options, selects the highest-scoring candidate.

With AgentDB: Before researching, the system queries reflexion memory for past discovery episodes in the same domain. If a previous creation already evaluated NOAA vs. Open-Meteo for climate data, the system reuses that evaluation (with a freshness check) instead of repeating the research from scratch.

AgentDB query: "What APIs were selected for climate/weather domains?"
Result: NOAA selected 3 times (avg score 8.7/10), Open-Meteo selected 2 times (9.1/10)
Effect: Open-Meteo is pre-ranked higher, saving 5-10 minutes of research

Phase 2: Design

Without AgentDB: System designs 4-6 analyses based on domain best practices and API capabilities.

With AgentDB: Causal reasoning identifies which analysis patterns have the highest success rates for the domain. Reflexion memory recalls which analyses users requested most frequently.

AgentDB query: "What analyses work best for financial skills?"
Result: Technical indicators (92% retention), sector comparison (87%),
        portfolio tracking (85%), news sentiment (61%)
Effect: News sentiment is deprioritized; technical indicators are designed first

Phase 3: Architecture

Without AgentDB: System chooses simple vs. complex architecture based on scope.

With AgentDB: Historical data on suite sizes vs. maintainability informs the decision. If past suites with 4+ components had refactoring issues, the system might recommend splitting differently.

AgentDB query: "What architecture works best for 3-workflow skills?"
Result: Simple skill chosen 8/10 times, suite chosen 2/10. Simple had
        fewer maintenance issues (causal link: simple -> 30% less rework)
Effect: Simple skill recommended with higher confidence

Phase 4: Detection

Without AgentDB: System generates description and keywords based on domain analysis.

With AgentDB: Extracted skills from past successful activations inform keyword selection. If "stock analysis" activated more reliably than "equity research" in past skills, the former is prioritized.

AgentDB query: "What keywords had highest activation rates for finance?"
Result: "stock analysis" (98%), "market data" (95%), "portfolio" (93%),
        "equity research" (72%), "securities" (68%)
Effect: High-activation keywords prioritized in description

Phase 5: Implementation

Without AgentDB: System creates all files following the standard pipeline.

With AgentDB: Learned improvements from past creations are applied. If a specific error-handling pattern reduced runtime failures, it is included automatically. After creation, the episode is stored for future learning.

AgentDB action: Store episode
  - Domain: climate
  - Template used: climate-analysis
  - APIs: Open-Meteo + NOAA
  - Analyses: 5 implemented
  - Validation: passed (10/10)
  - Security: passed (clean)
  - User satisfaction: pending

Learning Progression

AgentDB's value grows with usage. Here is what to expect at different stages.

First Creation (No History)

• AgentDB has no past episodes to draw from
• Behavior is identical to running without AgentDB
• The creation episode is stored for future reference
• No noticeable difference in output quality

After 5+ Creations

• Reflexion memory has enough episodes to identify domain patterns
• API selection benefits from past evaluations (fewer redundant searches)
• Common analysis patterns are recognized and reused
• Estimated time savings: 10-15% per creation

After 10+ Creations

• Causal reasoning has enough data to identify reliable cause-effect links
• Template matching improves as keyword effectiveness data accumulates
• Architecture decisions are informed by maintenance outcomes
• Skill extraction produces reusable patterns across domains
• Estimated time savings: 20-30% per creation

After 30+ Days of Usage

• Nightly learner has processed all episodes and extracted high-confidence patterns
• Cross-domain insights emerge (e.g., "caching improves all API-heavy skills by 25%")
• Template recommendations reach high accuracy (>90% user acceptance)
• The system begins suggesting proactive improvements to existing skills
• Estimated time savings: 30-40% per creation

Graceful Fallback

AgentDB availability is checked once at initialization. If unavailable, the system operates in fallback mode with zero user-visible impact.

Detection Order

1. Check for native agentdb CLI in PATH 2. Check for npx @anthropic-ai/agentdb availability 3. Attempt automatic installation via npm (if npm is available) 4. If all checks fail, enter fallback mode silently

Fallback Behavior

Error Tolerance

If AgentDB is available but encounters errors during operation:

• First 3 errors: Logged silently, operation retried with fallback
• After 3 errors: AgentDB is disabled for the remainder of the session
• Next session: AgentDB is re-initialized (errors do not persist across sessions)

No AgentDB error ever surfaces to the user or interrupts the creation pipeline.

Privacy and Performance

All Local

• AgentDB stores all data locally in ~/.agentdb/
• No data is transmitted to external servers
• No telemetry, analytics, or usage tracking
• The user's creation history stays on their machine

No External Dependencies at Runtime

• AgentDB is an npm package, but once installed it runs locally
• If npm is unavailable, AgentDB simply does not install (fallback mode)
• The skill creator itself has zero npm dependencies -- AgentDB is purely optional

Performance Impact

AgentDB operations are asynchronous where possible and never block the main creation pipeline.

Technical Implementation

Bridge Architecture

The integration uses a bridge pattern (integrations/agentdb_bridge.py) that isolates all AgentDB operations behind a clean interface:

from integrations.agentdb_bridge import enhance_agent_creation

# Called internally during skill creation -- never by the user
intelligence = enhance_agent_creation(
    user_input="Create a climate analysis skill",
    domain="climate"
)

# intelligence.template_choice -> "climate-analysis" (or None in fallback)
# intelligence.success_probability -> 0.87 (or 0.0 in fallback)
# intelligence.learned_improvements -> ["Use Open-Meteo over NOAA for forecasts"]

Module Functions

Configuration

AgentDB auto-configures on first use. The configuration lives at ~/.agentdb/config.json:

{
  "reflexion": {
    "auto_save": true,
    "compression": true
  },
  "causal": {
    "auto_track": true,
    "utility_model": "outcome_based"
  },
  "skills": {
    "auto_extract": true,
    "success_threshold": 0.8
  },
  "nightly_learner": {
    "enabled": true,
    "schedule": "2:00 AM"
  }
}

No user action is required to create or maintain this configuration. The bridge handles everything automatically.