pwn 0.5.632 → 0.5.634

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bea724f1a504fa45e1f4eaa786761599a75e08a07b5848327b1dafd61dbe6f2
-  data.tar.gz: 9a4e693fe7b54d7477896d78272fb5c87a42deb5719730489a0a623eb39230dd
+  metadata.gz: 8632bee6e87072a40fbd993834156ad06e1c448918b2922125d592debd7c033d
+  data.tar.gz: 399687f4f6ea85666f9e7d8e4c0450998be2949218b45d68b061e8c20c452010
 SHA512:
-  metadata.gz: 3998a8a58340cdf1c8b4a9ba9a57a8fe9fb7a749117a606f65b643996ec343606692d5382f71ccd6e119ceac6f995047092bdd87f2e14e8e575b1a306ee29b1f
-  data.tar.gz: c10128b60319de27d0404c18289b91dd40ca78ca18df522e788c6b2a968e85c8b71c49c2447ef6eee268538787c1b09ba786a303a9fe8eb5198912eb4834ab90
+  metadata.gz: 964a576117407e3e5907a302106c2a0f657bedc9a4ebd59167ca360f7f89dbcb3975aec4b6c036e3cc2f138461044f162371f8b2e62d05e5f0ca1c498fa852b4
+  data.tar.gz: 8cae2ebdeb246fc190c49aed8b5a787372a482e2eecc3027116eab1bca985b33d9451cd22df4f158f1d4e0e8dc4314f6b1754f4e3b42f68dd8f7c1808b7ea3e6

data/.github/workflows/install-matrix.yml

@@ -57,8 +57,8 @@ jobs:
         # Base axes → 5 images × 2 profiles = 10 legs.
         image:
           - kalilinux/kali-rolling
-          - debian:bookworm
-          - ubuntu:24.04
+          - debian:trixie
+          - ubuntu:latest
           - fedora:latest
           - archlinux:latest
         profile:
@@ -73,10 +73,10 @@ jobs:
           - image: kalilinux/kali-rolling
             pm: apt
             ruby: apt-get update && apt-get install -y ruby-full ruby-dev build-essential git
-          - image: debian:bookworm
+          - image: debian:trixie
             pm: apt
             ruby: apt-get update && apt-get install -y ruby-full ruby-dev build-essential git
-          - image: ubuntu:24.04
+          - image: ubuntu:latest
             pm: apt
             ruby: apt-get update && apt-get install -y ruby-full ruby-dev build-essential git
           - image: fedora:latest
@@ -95,8 +95,15 @@ jobs:
         run: ${{ matrix.ruby }}
 
       - name: checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
+
+      - name: trust git checkout owned by host UID (container job)
+        # actions/checkout marks the repo safe under a temp $HOME that doesn't
+        # survive into subsequent steps. Without this, `git ls-files` in
+        # pwn.gemspec (and any spec that shells out to git) fails with
+        # "detected dubious ownership" and the gem builds with ZERO files.
+        run: git config --global --add safe.directory "$PWD"
       - name: build & install gem from checkout (git-checkout path in doc)
         run: |
           gem build pwn.gemspec
@@ -124,7 +131,7 @@ jobs:
       PWN_EXPECTED_PM: brew
       PWN_PROFILE: core
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - uses: ruby/setup-ruby@v1
         with:
@@ -164,8 +171,11 @@ jobs:
     steps:
       - run: apt-get update && apt-get install -y ruby-full ruby-dev build-essential git
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+
 
+      - name: trust git checkout owned by host UID (container job)
+        run: git config --global --add safe.directory "$PWD"
       - name: run legacy provisioner (must delegate to `pwn setup`)
         run: bash packer/provisioners/pwn.sh
 

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops: 
   UseCache: false
+  SuggestExtensions: false
   NewCops: enable
 Layout/LineLength:
   Max: 1620

data/Gemfile

@@ -50,7 +50,7 @@ gem 'libusb', '0.7.2'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
 gem 'mcp', '0.24.0'
-gem 'meshtastic', '0.0.171'
+gem 'meshtastic', '0.0.172'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.24.1'
 gem 'msfrpc-client', '1.1.2'
@@ -105,4 +105,4 @@ gem 'webrick', '1.9.2'
 gem 'whois', '6.0.3'
 gem 'whois-parser', '2.0.0'
 gem 'wicked_pdf', '2.8.2'
-gem 'yard', '0.9.44'
+gem 'yard', '0.9.45'

data/Rakefile

@@ -20,5 +20,5 @@ if defined?(RDoc::Task)
 end
 
 default_tasks = %i[spec rubocop]
-default_tasks << :rdoc if defined?(RDoc::Task)
+default_tasks << :rerdoc if defined?(RDoc::Task)
 task default: default_tasks

data/bin/pwn_fuzz_net_app_proto

@@ -75,13 +75,7 @@ pwn_provider = 'ruby-gem'
 # pwn_provider = ENV.fetch('PWN_PROVIDER') if ENV.keys.select { |s| s == 'PWN_PROVIDER' }.any?
 pwn_provider = ENV.fetch('PWN_PROVIDER') if ENV.keys.any? { |s| s == 'PWN_PROVIDER' }
 
-if pwn_provider == 'ruby-gem'
-  require 'pwn'
-elsif pwn_provider == 'docker'
-  require '/opt/pwn/lib/pwn'
-else
-  raise "PWN_PROVIDER env variable is not set to 'ruby-gem' or 'docker'"
-end
+raise "PWN_PROVIDER env variable is not set to 'ruby-gem' or 'docker'" unless %w[ruby-gem docker].include?(pwn_provider)
 
 dir_path = opts[:dir_path] ||= '.'
 target = opts[:target]

data/documentation/Agent-Tool-Registry.md

@@ -13,9 +13,9 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `terminal` | `shell` | `Open3.capture3` on the host |
 | `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
-| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` | `~/.pwn/skills/*.md` |
+| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (agentskills.io; legacy flat `*.md` still read) |
 | `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
-| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** | `PWN::AI::Agent::Learning` + `PWN::AI::Agent::Mistakes` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · `learning_purge_noise` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` |
 | `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
 | `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser) → `~/.pwn/extrospection.json` |
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |

data/documentation/Installation.md

@@ -17,7 +17,7 @@ needed to unlock the ones you want. No `/opt/pwn` checkout, no `rvmsudo`
 chain, no bash provisioners required.
 
 Tested on **Kali / Debian / Ubuntu**, **Fedora**, **Arch**, and **macOS**
-(Homebrew or MacPorts). Ruby ≥ 3.4 (RVM, rbenv, asdf, or system Ruby).
+(Homebrew or MacPorts). Ruby ≥ 3.3 (RVM, rbenv, asdf, or system Ruby).
 
 ---
 

data/git_commit.sh

@@ -27,7 +27,7 @@ if (( $# == 3 )); then
   if [[ $? -ne 0 ]]; then
     echo 'ERROR: pwn_autoinc_version failed! Reinstalling pwn gemset...'
     rvmsudo ./reinstall_pwn_gemset.sh
-    rvmsudo rake
+    rake
     rvmsudo rake install
     if [[ $? -ne 0 ]]; then
       echo 'ERROR: Attempt to reinstall pwn gemset failed! Please investigate and fix before trying again.'

data/lib/pwn/ai/agent/learning.rb

@@ -225,26 +225,23 @@ module PWN
         # )
 
         public_class_method def self.distill_skill(opts = {})
-          name = opts[:name].to_s.gsub(/[^a-z0-9_-]/i, '_')
-          raise 'ERROR: name is required' if name.empty?
+          raise 'ERROR: name is required' if opts[:name].to_s.strip.empty?
 
           body = opts[:content].to_s
-          body = build_skill_from_session(session_id: opts[:session_id], name: name) if body.strip.empty? && opts[:session_id]
+          body = build_skill_from_session(session_id: opts[:session_id], name: opts[:name]) if body.strip.empty? && opts[:session_id]
           raise 'ERROR: content or session_id is required' if body.strip.empty?
 
-          refs = Array(opts[:references]).map(&:to_s).map(&:strip).reject(&:empty?).uniq
-          unless refs.empty?
-            body = "---\nreferences:\n#{refs.map { |r| "  - #{r}" }.join("\n")}\n---\n#{body}" unless body.start_with?("---\n")
-            body = "#{body.rstrip}\n\n## References\n#{refs.map { |r| "- #{r}" }.join("\n")}\n" unless body =~ /^\#{1,3}\s*References\s*$/i
-          end
-
-          dir = skills_dir
-          FileUtils.mkdir_p(dir)
-          path = File.join(dir, "#{name}.md")
-          File.write(path, body)
-          PWN::Config.load_skills(pwn_skills_path: dir) if defined?(PWN::Config) && PWN::Config.respond_to?(:load_skills)
-          note_outcome(task: "distill_skill:#{name}", success: true, details: "Saved #{path}", tags: %w[skill auto])
-          { saved: true, name: name, path: path, bytes: body.bytesize, references: refs }
+          root = skills_dir
+          out  = PWN::Config.write_skill(
+            name: opts[:name],
+            description: opts[:description],
+            content: body,
+            references: opts[:references],
+            pwn_skills_path: root
+          )
+          PWN::Config.load_skills(pwn_skills_path: root) if PWN::Config.respond_to?(:load_skills)
+          note_outcome(task: "distill_skill:#{out[:name]}", success: true, details: "Saved #{out[:path]}", tags: %w[skill auto])
+          out.merge(saved: true)
         end
 
         # Supported Method Parameters::

data/lib/pwn/ai/agent/prompt_builder.rb

@@ -117,11 +117,15 @@ module PWN
           return '' unless defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) && !PWN::Skills.empty?
 
           lines = PWN::Skills.map do |name, meta|
-            first = meta[:content].to_s.lines.reject { |l| l.strip.empty? || l.start_with?('---') }.first.to_s.strip
-            first = first[0, 100]
+            desc = meta[:description].to_s.strip
+            if desc.empty?
+              # legacy / stubbed entry without a parsed description — fall back
+              desc = meta[:content].to_s.lines.reject { |l| l.strip.empty? || l.start_with?('---') }.first.to_s.strip
+            end
+            desc = desc[0, 100]
             rc = Array(meta[:references]).length
             ref_tag = rc.positive? ? " [#{rc} refs]" : ''
-            "  - #{name}: #{first}#{ref_tag}"
+            "  - #{name}: #{desc}#{ref_tag}"
           end
           "SKILLS (call skill_view to read full body)\n#{lines.join("\n")}\n\n"
         rescue StandardError

data/lib/pwn/ai/agent/tools/skills.rb

@@ -3,14 +3,23 @@
 require 'fileutils'
 require 'pwn/ai/agent/registry'
 
-# Thin wrappers around the PWN::Skills store (~/.pwn/skills/*.md) so the
-# model can list/read/write reusable procedures. PromptBuilder injects
-# the index (name + first line); skill_view loads the full body on demand.
+# Thin wrappers around the PWN::Skills store so the model can list / read /
+# write reusable procedures. PromptBuilder injects the index (name +
+# description); skill_view loads the full body on demand — the two-tier
+# progressive-disclosure pattern from https://agentskills.io/specification.
+#
+# On disk (spec-conformant, written by PWN::Config.write_skill):
+#   ~/.pwn/skills/<name>/SKILL.md      ← YAML frontmatter (name, description, …)
+#   ~/.pwn/skills/<name>/scripts/      ← optional executable helpers
+#   ~/.pwn/skills/<name>/references/   ← optional supporting docs
+#
+# Legacy flat ~/.pwn/skills/<name>.md files are still LOADED (format:
+# :legacy) so existing installs keep working; new writes always use the
+# directory layout. Run PWN::Config.migrate_legacy_skills to convert.
 #
 # Each skill may carry a :references Array (URLs, CWE/CVE/ATT&CK ids,
-# NIST 800-53 controls, docs) parsed from YAML front-matter or a
-# "## References" markdown section. References let the agent cite
-# authoritative sources when applying a skill and mirror the
+# NIST 800-53 controls, docs) parsed from frontmatter `metadata.references`
+# and/or a "## References" markdown section — mirroring the
 # PWN::SAST::*.security_references convention.
 
 PWN::AI::Agent::Registry.register(
@@ -18,7 +27,7 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_list',
-    description: 'List available pwn-ai skills (name + first line + reference count).',
+    description: 'List available pwn-ai skills (name + description + reference count + format).',
     parameters: { type: 'object', properties: {}, required: [] }
   },
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
@@ -27,7 +36,8 @@ PWN::AI::Agent::Registry.register(
       {
         name: name,
         type: meta[:type],
-        summary: meta[:content].to_s.lines.first.to_s.strip[0, 120],
+        format: meta[:format] || :legacy,
+        description: (meta[:description] || meta[:content].to_s.lines.first.to_s.strip)[0, 200],
         references: Array(meta[:references]).length
       }
     end
@@ -39,7 +49,7 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_view',
-    description: 'Read the full content of a named skill, including its references.',
+    description: 'Read the full content of a named skill, including its frontmatter and references.',
     parameters: {
       type: 'object',
       properties: { name: { type: 'string' } },
@@ -49,13 +59,17 @@ PWN::AI::Agent::Registry.register(
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
   handler: lambda { |args|
     key = args[:name].to_s.to_sym
-    meta = PWN::Skills[key]
+    meta = PWN::Skills[key] || PWN::Skills[PWN::Config.sanitize_skill_name(name: key).to_sym]
     raise ArgumentError, "no such skill: #{key}" unless meta
 
     {
       name: key,
       type: meta[:type],
+      format: meta[:format] || :legacy,
       path: meta[:path],
+      dir: meta[:dir],
+      description: meta[:description],
+      frontmatter: meta[:frontmatter] || {},
       references: Array(meta[:references]),
       content: meta[:content]
     }
@@ -67,49 +81,46 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_create',
-    description: 'Save a new reusable skill (markdown procedure) to ~/.pwn/skills/. ' \
-                 'It will be listed in every future pwn-ai system prompt. Optionally ' \
-                 'attach references (URLs, CWE/CVE ids, MITRE ATT&CK, NIST 800-53, docs).',
+    description: 'Save a new reusable skill to ~/.pwn/skills/<name>/SKILL.md ' \
+                 '(agentskills.io format: required name + description YAML ' \
+                 'frontmatter). Appears in every future pwn-ai system prompt. ' \
+                 'Optionally attach references (URLs, CWE/CVE ids, MITRE ' \
+                 'ATT&CK, NIST 800-53, docs) and an allowed-tools allowlist.',
     parameters: {
       type: 'object',
       properties: {
-        name: { type: 'string', description: 'lowercase, hyphens/underscores only' },
-        content: { type: 'string', description: 'Full markdown body of the skill.' },
+        name: { type: 'string', description: 'Free-form; sanitised to [a-z0-9-]{1,64} per spec.' },
+        description: { type: 'string', description: '1..1024 char summary shown in the SKILLS index. Derived from body when omitted.' },
+        content: { type: 'string', description: 'Full markdown body of the skill (WITHOUT frontmatter — it is generated).' },
         references: {
           type: 'array',
           items: { type: 'string' },
           description: 'Optional list of reference URLs / identifiers (CWE-79, T1059, ' \
-                       'https://..., NIST SI-3, etc.). Written as YAML front-matter and ' \
-                       'a "## References" section.'
-        }
+                       'https://..., NIST SI-3, etc.). Written under frontmatter ' \
+                       'metadata.references and as a "## References" section.'
+        },
+        license: { type: 'string', description: 'Optional SPDX identifier or free text.' },
+        allowed_tools: { type: 'array', items: { type: 'string' }, description: 'Optional toolset allowlist for this skill.' },
+        metadata: { type: 'object', description: 'Optional arbitrary metadata hash.' }
       },
       required: %w[name content]
     }
   },
-  check: -> { defined?(PWN::Config) && PWN::Config.respond_to?(:pwn_skills_path) },
+  check: -> { defined?(PWN::Config) && PWN::Config.respond_to?(:write_skill) },
   handler: lambda { |args|
-    name = args[:name].to_s.gsub(/[^a-z0-9_-]/i, '_')
-    raise ArgumentError, 'name is required' if name.empty?
-
-    body = args[:content].to_s
-    refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?).uniq
-
-    unless refs.empty?
-      # YAML front-matter (only if body doesn't already have one)
-      unless body.start_with?("---\n")
-        fm = "---\nreferences:\n#{refs.map { |r| "  - #{r}" }.join("\n")}\n---\n"
-        body = fm + body
-      end
-      # ## References section (only if not already present)
-      body = "#{body.rstrip}\n\n## References\n#{refs.map { |r| "- #{r}" }.join("\n")}\n" unless body =~ /^\#{1,3}\s*References\s*$/i
-    end
-
-    dir = PWN::Config.pwn_skills_path
-    FileUtils.mkdir_p(dir)
-    path = File.join(dir, "#{name}.md")
-    File.write(path, body)
-    PWN::Config.load_skills(pwn_skills_path: dir) # refresh PWN::Skills const
-    { saved: true, path: path, references: refs, total: PWN::Skills.keys.length }
+    root = PWN::Config.pwn_skills_path
+    out  = PWN::Config.write_skill(
+      name: args[:name],
+      description: args[:description],
+      content: args[:content],
+      references: args[:references],
+      license: args[:license],
+      allowed_tools: args[:allowed_tools],
+      metadata: args[:metadata],
+      pwn_skills_path: root
+    )
+    PWN::Config.load_skills(pwn_skills_path: root)
+    out.merge(saved: true, total: PWN::Skills.keys.length)
   }
 )
 
@@ -119,7 +130,8 @@ PWN::AI::Agent::Registry.register(
   schema: {
     name: 'skill_add_reference',
     description: 'Append one or more references (URL, CWE/CVE id, MITRE ATT&CK ' \
-                 'technique, NIST control, doc link) to an existing skill.',
+                 'technique, NIST control, doc link) to an existing skill. ' \
+                 'Rewrites frontmatter metadata.references + ## References section.',
     parameters: {
       type: 'object',
       properties: {
@@ -132,31 +144,50 @@ PWN::AI::Agent::Registry.register(
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
   handler: lambda { |args|
     key  = args[:name].to_s.to_sym
-    meta = PWN::Skills[key]
+    meta = PWN::Skills[key] || PWN::Skills[PWN::Config.sanitize_skill_name(name: key).to_sym]
     raise ArgumentError, "no such skill: #{key}" unless meta
 
     new_refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?)
     raise ArgumentError, 'references must be a non-empty array' if new_refs.empty?
 
-    body     = File.read(meta[:path])
+    root     = PWN::Config.pwn_skills_path
     existing = Array(meta[:references])
-    add      = (new_refs - existing)
-
-    if body =~ /^(\#{1,3}\s*References\s*)$/i
-      # Append bullets right after the References heading block (end of file safest)
-      body = "#{body.rstrip}\n#{add.map { |r| "- #{r}" }.join("\n")}\n" unless add.empty?
+    combined = (existing + new_refs).uniq
+    added    = combined - existing
+
+    if meta[:format] == :agentskills
+      # Rewrite via the canonical writer so frontmatter stays valid.
+      body = PWN::Config.parse_skill_frontmatter(content: meta[:content])[:body]
+                        .to_s.sub(/^\#{1,3}\s*References\s*$.*\z/mi, '').rstrip
+      PWN::Config.write_skill(
+        name: key.to_s,
+        description: meta[:description],
+        content: body,
+        references: combined,
+        license: (meta[:frontmatter] || {})['license'],
+        allowed_tools: meta[:allowed_tools],
+        metadata: (meta[:frontmatter] || {})['metadata'],
+        pwn_skills_path: root
+      )
     else
-      body = "#{body.rstrip}\n\n## References\n#{(existing + add).uniq.map { |r| "- #{r}" }.join("\n")}\n"
+      # Legacy flat file — append to (or create) the ## References section in place.
+      body = File.read(meta[:path])
+      body = if body =~ /^(\#{1,3}\s*References\s*)$/i
+               "#{body.rstrip}\n#{added.map { |r| "- #{r}" }.join("\n")}\n"
+             else
+               "#{body.rstrip}\n\n## References\n#{combined.map { |r| "- #{r}" }.join("\n")}\n"
+             end
+      File.write(meta[:path], body)
     end
 
-    File.write(meta[:path], body)
-    PWN::Config.load_skills(pwn_skills_path: File.dirname(meta[:path]))
+    PWN::Config.load_skills(pwn_skills_path: root)
+    reloaded = PWN::Skills[key] || PWN::Skills[PWN::Config.sanitize_skill_name(name: key).to_sym]
     {
       saved: true,
       name: key,
-      path: meta[:path],
-      added: add,
-      references: Array(PWN::Skills[key][:references])
+      path: reloaded[:path],
+      added: added,
+      references: Array(reloaded[:references])
     }
   }
 )
@@ -166,13 +197,15 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_delete',
-    description: 'Delete a skill from ~/.pwn/skills/ by name. Use to prune ' \
-                 'low-quality auto-distilled skills so they stop appearing ' \
-                 'in every future system prompt. Irreversible.',
+    description: 'Delete a skill from ~/.pwn/skills/ by name. Removes the ' \
+                 'entire <name>/ directory (agentskills format) or the flat ' \
+                 'file (legacy). Use to prune low-quality auto-distilled ' \
+                 'skills so they stop appearing in every future system prompt. ' \
+                 'Irreversible.',
     parameters: {
       type: 'object',
       properties: {
-        name: { type: 'string', description: 'Existing skill name (basename without extension).' }
+        name: { type: 'string', description: 'Existing skill name.' }
       },
       required: %w[name]
     }
@@ -180,13 +213,39 @@ PWN::AI::Agent::Registry.register(
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
   handler: lambda { |args|
     key  = args[:name].to_s.to_sym
-    meta = PWN::Skills[key]
+    meta = PWN::Skills[key] || PWN::Skills[PWN::Config.sanitize_skill_name(name: key).to_sym]
     raise ArgumentError, "no such skill: #{key}" unless meta
 
+    root = PWN::Config.pwn_skills_path
     path = meta[:path]
-    dir  = File.dirname(path)
-    FileUtils.rm_f(path)
-    PWN::Config.load_skills(pwn_skills_path: dir)
+    if meta[:format] == :agentskills && meta[:dir] && File.basename(File.dirname(path)) == File.basename(meta[:dir])
+      FileUtils.rm_rf(meta[:dir])
+    else
+      FileUtils.rm_f(path)
+    end
+    PWN::Config.load_skills(pwn_skills_path: root)
     { deleted: true, name: key, path: path, remaining: PWN::Skills.keys.length }
   }
 )
+
+PWN::AI::Agent::Registry.register(
+  name: 'skill_migrate_legacy',
+  toolset: 'skills',
+  schema: {
+    name: 'skill_migrate_legacy',
+    description: 'One-shot: convert every legacy flat ~/.pwn/skills/*.md into ' \
+                 'a spec-conformant <name>/SKILL.md with backfilled name + ' \
+                 'description frontmatter. Idempotent; safe to re-run.',
+    parameters: {
+      type: 'object',
+      properties: {
+        delete_legacy: { type: 'boolean', default: true, description: 'Remove the flat file after migration.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::Config) && PWN::Config.respond_to?(:migrate_legacy_skills) },
+  handler: lambda { |args|
+    PWN::Config.migrate_legacy_skills(delete_legacy: args.fetch(:delete_legacy, true))
+  }
+)