From 1b394b808b0addf9be4a76f77888deba973703e5 Mon Sep 17 00:00:00 2001
From: 0xallam <ahmed39652003@gmail.com>
Date: Wed, 21 Jan 2026 14:50:48 -0800
Subject: [PATCH] docs: update skills documentation for markdown format

Reflect PR #275 changes - skills now use Markdown files with YAML
frontmatter instead of Jinja templates with XML-style tags.
---
 docs/advanced/skills.mdx | 36 +++++++++++++++++++-----------------
 docs/contributing.mdx    |  2 +-
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/docs/advanced/skills.mdx b/docs/advanced/skills.mdx
index cbbcad6..5345600 100644
--- a/docs/advanced/skills.mdx
+++ b/docs/advanced/skills.mdx
@@ -83,35 +83,37 @@ Protocol-specific testing techniques.
 
 ## Skill Structure
 
-Each skill uses XML-style tags for structure:
+Each skill is a Markdown file with YAML frontmatter for metadata:
 
-```xml
-<vulnerability_guide>
-  <title>NAME</title>
+```markdown
+---
+name: skill_name
+description: Brief description of the skill's coverage
+---
 
-  <critical>Key insight about this vulnerability</critical>
+# Skill Title
 
-  <scope>What this skill covers</scope>
+Key insight about this vulnerability or technique.
 
-  <methodology>Step-by-step testing approach</methodology>
+## Attack Surface
+What this skill covers and where to look.
 
-  <discovery_techniques>How to find it</discovery_techniques>
+## Methodology
+Step-by-step testing approach.
 
-  <exploitation_techniques>How to exploit it</exploitation_techniques>
+## Techniques
+How to discover and exploit the vulnerability.
 
-  <bypass_techniques>How to bypass protections</bypass_techniques>
+## Bypass Methods
+How to bypass common protections.
 
-  <validation>How to confirm findings</validation>
-
-  <false_positives>What to watch out for</false_positives>
-
-  <pro_tips>Additional Expert advice</pro_tips>
-</vulnerability_guide>
+## Validation
+How to confirm findings and avoid false positives.
 ```
 
 ## Contributing Skills
 
-Community contributions are welcome. Good skills include:
+Community contributions are welcome. Create a `.md` file in the appropriate category with YAML frontmatter (`name` and `description` fields). Good skills include:
 
 1. **Real-world techniques** — Methods that work in practice
 2. **Practical payloads** — Working examples with variations
diff --git a/docs/contributing.mdx b/docs/contributing.mdx
index 830ec9b..14daeb6 100644
--- a/docs/contributing.mdx
+++ b/docs/contributing.mdx
@@ -50,7 +50,7 @@ Skills are specialized knowledge packages that enhance agent capabilities. They
 ### Creating a Skill
 
 1. Choose the right category
-2. Create a `.jinja` file with your skill content
+2. Create a `.md` file with YAML frontmatter (`name` and `description` fields)
 3. Include practical examples—working payloads, commands, test cases
 4. Provide validation methods to confirm findings
 5. Submit via PR