ma-agents 1.1.0

package/skills/git-workflow-skill/scripts/validate-workflow.sh

@@ -0,0 +1,229 @@
+#!/bin/bash
+# validate-workflow.sh - Check if current state follows git workflow rules
+# Usage: validate-workflow.sh [--list]
+#
+# Worktree-aware: detects whether you're in a worktree or main repo
+# and validates accordingly.
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+ERRORS=0
+WARNINGS=0
+
+error() { echo -e "${RED}x ERROR: $1${NC}"; ERRORS=$((ERRORS + 1)); }
+warn() { echo -e "${YELLOW}! WARNING: $1${NC}"; WARNINGS=$((WARNINGS + 1)); }
+ok() { echo -e "${GREEN}+ $1${NC}"; }
+info() { echo -e "  $1"; }
+
+# Handle --list flag to show active worktrees
+if [[ "$1" == "--list" ]]; then
+    echo "Active Worktrees"
+    echo "================"
+    git worktree list 2>/dev/null || echo "Not in a git repository"
+    exit 0
+fi
+
+echo "Git Workflow Validation (Worktree-Aware)"
+echo "========================================="
+echo ""
+
+# Check we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    error "Not in a git repository"
+    exit 1
+fi
+
+# Detect worktree status
+GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+CURRENT_DIR=$(git rev-parse --show-toplevel)
+
+IS_WORKTREE=false
+if [[ "$GIT_COMMON" != "$GIT_DIR" && "$GIT_COMMON" != "." ]]; then
+    IS_WORKTREE=true
+    MAIN_REPO=$(cd "$GIT_COMMON/.." && pwd)
+    echo -e "${CYAN}Context: Inside worktree${NC}"
+    info "Worktree: $CURRENT_DIR"
+    info "Main repo: $MAIN_REPO"
+else
+    MAIN_REPO="$CURRENT_DIR"
+    echo -e "${CYAN}Context: Main repository${NC}"
+    info "Repo: $MAIN_REPO"
+fi
+
+# Get current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "Branch: $CURRENT_BRANCH"
+echo ""
+
+# Check 1: Not on protected branch
+echo "Checking branch..."
+if [[ "$CURRENT_BRANCH" == "dev" || "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+    if [[ "$IS_WORKTREE" == true ]]; then
+        error "Worktree is on protected branch '$CURRENT_BRANCH'. Worktrees should be on feature branches."
+    else
+        # Main repo on dev is fine — that's the expected state
+        ok "Main repo is on '$CURRENT_BRANCH' (expected)"
+    fi
+else
+    ok "On feature branch '$CURRENT_BRANCH'"
+fi
+
+# Check 2: Branch naming convention (only for feature branches)
+if [[ "$CURRENT_BRANCH" != "dev" && "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
+    if echo "$CURRENT_BRANCH" | grep -qE '^(feature|bugfix|hotfix|chore)/[a-z0-9-]+$'; then
+        ok "Branch name follows convention"
+    else
+        warn "Branch name '$CURRENT_BRANCH' doesn't follow convention: <type>/<description>"
+        info "Expected: feature|bugfix|hotfix|chore followed by lowercase alphanumeric with dashes"
+    fi
+fi
+
+# Check 3: dev branch exists
+echo ""
+echo "Checking repository setup..."
+git fetch origin 2>/dev/null || warn "Could not fetch from origin"
+
+if git branch -a | grep -qE '(^|\s)origin/dev$'; then
+    ok "Remote 'dev' branch exists"
+else
+    error "Remote 'dev' branch not found. Create it before using this workflow."
+fi
+
+# Check 4: Up to date with dev (for feature branches)
+echo ""
+echo "Checking sync status..."
+if [[ "$CURRENT_BRANCH" != "dev" && "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
+    if git branch -a | grep -qE '(^|\s)origin/dev$'; then
+        BEHIND=$(git rev-list --count HEAD..origin/dev 2>/dev/null || echo "0")
+        if [[ "$BEHIND" == "0" ]]; then
+            ok "Branch is up to date with dev"
+        else
+            warn "Branch is $BEHIND commit(s) behind dev. Consider rebasing."
+            info "Run: git fetch origin dev && git rebase origin/dev"
+        fi
+    fi
+else
+    ok "On base branch — sync check not needed"
+fi
+
+# Check 5: Uncommitted changes
+echo ""
+echo "Checking working directory..."
+if git diff-index --quiet HEAD -- 2>/dev/null; then
+    ok "No uncommitted changes"
+else
+    warn "Uncommitted changes detected"
+    info "Run: git status"
+fi
+
+# Check 6: Untracked files (that aren't ignored)
+UNTRACKED=$(git ls-files --others --exclude-standard | wc -l)
+if [[ "$UNTRACKED" -gt 0 ]]; then
+    warn "$UNTRACKED untracked file(s) found"
+    info "Run: git status"
+else
+    ok "No untracked files"
+fi
+
+# Check 7: Validate recent commit messages (for feature branches)
+echo ""
+echo "Checking commit messages..."
+if [[ "$CURRENT_BRANCH" != "dev" && "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
+    COMMITS=$(git rev-list --count origin/dev..HEAD 2>/dev/null || echo "0")
+    if [[ "$COMMITS" -gt 0 ]]; then
+        INVALID=0
+        while IFS= read -r msg; do
+            if ! echo "$msg" | grep -qE '^(feat|fix|chore|docs|refactor|test)(\([^)]+\))?: .+'; then
+                INVALID=$((INVALID + 1))
+            fi
+        done < <(git log origin/dev..HEAD --pretty=format:"%s" 2>/dev/null)
+
+        if [[ "$INVALID" -eq 0 ]]; then
+            ok "All $COMMITS commit(s) follow conventional format"
+        else
+            warn "$INVALID of $COMMITS commit(s) don't follow conventional format"
+            info "Format: <type>(<scope>): <description>"
+            info "Types: feat, fix, chore, docs, refactor, test"
+        fi
+    else
+        info "No commits ahead of dev yet"
+    fi
+else
+    info "On base branch — commit check not needed"
+fi
+
+# Check 8: Git hooks installed
+echo ""
+echo "Checking git hooks..."
+HOOKS_DIR="${GIT_COMMON}/hooks"
+if [[ "$IS_WORKTREE" == true ]]; then
+    # Worktrees share hooks with the main repo
+    HOOKS_DIR="${GIT_COMMON}/hooks"
+fi
+
+if [[ -f "$HOOKS_DIR/pre-commit" && -x "$HOOKS_DIR/pre-commit" ]]; then
+    ok "pre-commit hook installed"
+else
+    warn "pre-commit hook not installed"
+    info "Run: ./scripts/install-hooks.sh"
+fi
+
+if [[ -f "$HOOKS_DIR/commit-msg" && -x "$HOOKS_DIR/commit-msg" ]]; then
+    ok "commit-msg hook installed"
+else
+    warn "commit-msg hook not installed"
+    info "Run: ./scripts/install-hooks.sh"
+fi
+
+# Check 9: Worktree health
+echo ""
+echo "Checking worktrees..."
+WORKTREE_COUNT=$(git worktree list | wc -l)
+ok "$WORKTREE_COUNT worktree(s) registered"
+
+# Check for stale worktrees
+STALE_COUNT=$(git worktree list --porcelain | grep -c "^prunable" 2>/dev/null || echo "0")
+if [[ "$STALE_COUNT" -gt 0 ]]; then
+    warn "$STALE_COUNT stale worktree(s) found"
+    info "Run: git worktree prune"
+else
+    ok "No stale worktrees"
+fi
+
+# Check .worktrees in .gitignore
+if [[ -f "${MAIN_REPO}/.gitignore" ]]; then
+    if grep -q '^\.worktrees' "${MAIN_REPO}/.gitignore" 2>/dev/null; then
+        ok ".worktrees/ is in .gitignore"
+    else
+        warn ".worktrees/ is NOT in .gitignore"
+        info "Add '.worktrees/' to your .gitignore"
+    fi
+fi
+
+# List active worktrees
+echo ""
+echo "Active worktrees:"
+git worktree list | while IFS= read -r line; do
+    echo "  $line"
+done
+
+# Summary
+echo ""
+echo "========================================="
+if [[ $ERRORS -gt 0 ]]; then
+    echo -e "${RED}Validation failed: $ERRORS error(s), $WARNINGS warning(s)${NC}"
+    exit 1
+elif [[ $WARNINGS -gt 0 ]]; then
+    echo -e "${YELLOW}Validation passed with $WARNINGS warning(s)${NC}"
+    exit 0
+else
+    echo -e "${GREEN}Validation passed: All checks OK${NC}"
+    exit 0
+fi

package/skills/git-workflow-skill/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "Git Workflow",
+  "description": "Worktree-based feature branch workflow for parallel multi-agent development with conventional commits and PR-based merging",
+  "version": "2.0.0",
+  "author": "AI Agent Skills",
+  "tags": ["git", "worktrees", "workflow", "branching", "conventional-commits", "pull-requests", "multi-agent"]
+}

package/skills/js-ts-security-skill/README.md

@@ -0,0 +1,28 @@
+# JS/TS Security Skill (OWASP 2025)
+
+Comprehensive security verification for JavaScript and TypeScript codebases following **OWASP Top 10 2025** standards.
+
+## Usage
+
+```bash
+# Verify security of the current project
+./skills/js-ts-security-skill/scripts/verify-security.sh
+```
+
+## Features
+
+- ✅ **Dependency Auditing**: Checks for known vulnerabilities in `node_modules`.
+- ✅ **Static Analysis**: Detects dangerous code patterns (eval, unsafe regex, etc.).
+- ✅ **Secret Scanning**: Finds hardcoded credentials and API keys.
+- ✅ **OWASP Compliance**: Maps findings to OWASP Top 10 categories.
+- ✅ **Actionable Reports**: Provides clear instructions on how to fix identified issues.
+
+## Requirements
+
+- Node.js and npm/yarn
+- `eslint` (installed in the project or globally)
+- `eslint-plugin-security` (recommended for better results)
+
+## Configuration
+
+You can customize the audit by adding a `.securityrc` or specifying excludes in the script, though the default settings are designed to be comprehensive.

package/skills/js-ts-security-skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: js-ts-security-skill
+description: Verify the security of JavaScript and TypeScript codebases against OWASP Top 10 2025 standards.
+---
+
+# JS/TS Security Skill
+
+This skill provides a set of tools and best practices to ensure that JavaScript and TypeScript code (both client-side and server-side) is secure and compliant with the latest security standards, specifically the **OWASP Top 10 2025**.
+
+## When to Use
+- Before committing code to a repository.
+- During a security audit of an existing codebase.
+- When adding new dependencies or updating CI/CD pipelines.
+- When implementing critical features like authentication, authorization, or error handling.
+
+## Security Checks (OWASP 2025 Mapping)
+
+### A01:2025 - Broken Access Control
+- Verification of authorization logic.
+- **SSRF (Server-Side Request Forgery)**: Detecting unvalidated URL fetching in `fetch`, `axios`, `http.get`.
+
+### A02:2025 - Security Misconfiguration
+- Auditing configuration files (`.env`, `docker-compose.yml`).
+- Checking for insecure defaults and exposed debug endpoints.
+
+### A03:2025 - Software Supply Chain Failures
+- **NEW**: Focusing on dependency integrity.
+- Verification of lockfiles (`package-lock.json`, `yarn.lock`).
+- Checking for insecure registry URLs (HTTP).
+
+### A04:2025 - Cryptographic Failures
+- Detecting weak hashing (MD5, SHA1).
+- Checking for insecure randomness (`Math.random()`).
+
+### A05:2025 - Injection
+- Expanded detection for OS commands (`child_process.exec`), SQL injection, and NoSQL injection.
+
+### A06:2025 - Insecure Design
+- Documentation on secure design principles (e.g., Fail Secure, Least Privilege).
+
+### A07:2025 - Authentication Failures
+- Checking for insecure cookies (`httpOnly: false`).
+- Hardcoded credentials and weak session management.
+
+### A08:2025 - Software or Data Integrity Failures
+- Detecting unsafe deserialization (`unserialize`, `JSON.parse` of untrusted input).
+
+### A09:2025 - Logging & Alerting Failures
+- Identifying lack of security logging.
+- Empty catch blocks that swallow security errors.
+
+### A10:2025 - Mishandling of Exceptional Conditions
+- **NEW**: Identifying insecure error handling.
+- Detecting empty `catch` blocks and `console.log(err)` in critical paths.
+
+## Usage
+
+### Run OWASP 2025 Security Scan
+The primary method for automated security verification is the `verify-security.sh` script. This script executes multiple scanning phases (SAST, Audit, Secret Scanning) and maps all findings directly to OWASP 2025 categories.
+
+Run the scan from the project root:
+```bash
+/d/Code/agents/skills/js-ts-security-skill/scripts/verify-security.sh
+```

package/skills/js-ts-security-skill/scripts/verify-security.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+
+# JS/TS Security Verification Script (OWASP Top 10 2025)
+# This script performs a series of security checks on a JavaScript/TypeScript project.
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+echo -e "${CYAN}====================================================${NC}"
+echo -e "${CYAN}   JS/TS Security Audit - OWASP Top 10 2025         ${NC}"
+echo -e "${CYAN}====================================================${NC}\n"
+
+# A03:2025 - Software Supply Chain Failures
+echo -e "${YELLOW}[1/5] A03:2025 - Software Supply Chain Failures${NC}"
+SUPPLY_CHAIN_ISSUES=0
+if [ ! -f "package-lock.json" ] && [ ! -f "yarn.lock" ] && [ ! -f "pnpm-lock.yaml" ]; then
+    echo -e "${RED}✗ CRITICAL: No lockfile found (package-lock.json, yarn.lock, or pnpm-lock.yaml).${NC}"
+    echo "  Impact: Non-deterministic builds increase supply chain vulnerability."
+    SUPPLY_CHAIN_ISSUES=$((SUPPLY_CHAIN_ISSUES + 1))
+fi
+
+HTTP_REGISTRY=$(grep -r "http://" package.json 2>/dev/null)
+if [ ! -z "$HTTP_REGISTRY" ]; then
+    echo -e "${RED}✗ WARNING: Insecure registry found in package.json (using HTTP instead of HTTPS).${NC}"
+    echo "$HTTP_REGISTRY"
+    SUPPLY_CHAIN_ISSUES=$((SUPPLY_CHAIN_ISSUES + 1))
+fi
+
+if [ $SUPPLY_CHAIN_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ No immediate supply chain issues found.${NC}\n"
+else
+    echo -e "${RED}✗ Total supply chain issues: $SUPPLY_CHAIN_ISSUES${NC}\n"
+fi
+
+# A03:2025 / A06:2021 - Dependency Audit
+echo -e "${YELLOW}[2/5] A03:2025 - Vulnerable Components (Audit)${NC}"
+if [ -f "package-lock.json" ]; then
+    npm audit --audit-level=high
+    AUDIT_EXIT=$?
+elif [ -f "yarn.lock" ]; then
+    yarn audit --level high
+    AUDIT_EXIT=$?
+else
+    echo -e "${YELLOW}  Skipping dependency audit: No lockfile found.${NC}"
+    AUDIT_EXIT=0
+fi
+
+if [ $AUDIT_EXIT -eq 0 ]; then
+    echo -e "${GREEN}✓ No high-severity vulnerabilities in dependencies.${NC}\n"
+else
+    echo -e "${RED}✗ Vulnerabilities found. Run 'npm audit fix'.${NC}\n"
+fi
+
+# A01/A04/A05/A08 - Static Analysis (SAST)
+echo -e "${YELLOW}[3/5] Static Analysis (OWASP A01, A04, A05, A08)${NC}"
+declare -A DANGEROUS_PATTERNS
+DANGEROUS_PATTERNS["A01: SSRF/Access Control"]="fetch\(\`|axios\.get\(\`|http\.get\(\`"
+DANGEROUS_PATTERNS["A05: Injection"]="eval\(|new Function\(|child_process\.exec\(|require\('child_process'\)\.exec"
+DANGEROUS_PATTERNS["A04: Cryptographic Failures"]="crypto\.createHash\('md5'\)|crypto\.createHash\('sha1'\)|Math\.random\(\)"
+DANGEROUS_PATTERNS["A08: Software/Data Integrity"]="unserialize\(|JSON\.parse\("
+DANGEROUS_PATTERNS["A07: Authentication Failures"]="res\.cookie\(.*httpOnly: false|res\.cookie\(.*secure: false"
+
+FOUND_ISSUES=0
+for cat in "A01: SSRF/Access Control" "A05: Injection" "A04: Cryptographic Failures" "A08: Software/Data Integrity" "A07: Authentication Failures"; do
+    pattern=${DANGEROUS_PATTERNS[$cat]}
+    MATCHES=$(grep -rnE "$pattern" --include="*.js" --include="*.ts" --exclude-dir=node_modules . 2>/dev/null)
+    if [ ! -z "$MATCHES" ]; then
+        echo -e "${RED}✗ Found Risk: [$cat]${NC}"
+        echo "$MATCHES" | sed 's/^/  /'
+        FOUND_ISSUES=$((FOUND_ISSUES + 1))
+    fi
+done
+
+if [ $FOUND_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ No dangerous patterns detected via SAST.${NC}\n"
+else
+    echo -e "${RED}✗ Total dangerous patterns: $FOUND_ISSUES${NC}\n"
+fi
+
+# A10:2025 - Mishandling of Exceptional Conditions
+echo -e "${YELLOW}[4/5] A10:2025 - Mishandling of Exceptional Conditions${NC}"
+EMPTY_CATCH=$(grep -rnE "catch\s*\(\w*\)\s*\{\s*\}" --include="*.js" --include="*.ts" --exclude-dir=node_modules . 2>/dev/null)
+FOUND_EXCEPTION_ISSUES=0
+if [ ! -z "$EMPTY_CATCH" ]; then
+    echo -e "${RED}✗ Found Risk: Empty catch blocks (Swallowing exceptions)${NC}"
+    echo "$EMPTY_CATCH" | sed 's/^/  /'
+    FOUND_EXCEPTION_ISSUES=$((FOUND_EXCEPTION_ISSUES + 1))
+fi
+
+if [ $FOUND_EXCEPTION_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ Exception handling patterns appear secure.${NC}\n"
+else
+    echo -e "${RED}✗ Total exception handling issues: $FOUND_EXCEPTION_ISSUES${NC}\n"
+fi
+
+# Secret Detection (A01/A07)
+echo -e "${YELLOW}[5/5] A01/A07 - Hardcoded Secrets Scanning${NC}"
+SECRET_PATTERNS=("AIza[0-9A-Za-z-_]{35}" "sk_live_[0-9a-zA-Z]{24}" "xox[pb]-[0-9]{12}-[0-9]{12}-[0-9]{12}-[a-z0-9]{32}" "-----BEGIN RSA PRIVATE KEY-----")
+
+FOUND_SECRETS=0
+for pattern in "${SECRET_PATTERNS[@]}"; do
+    MATCHES=$(grep -rnE "$pattern" --include="*.js" --include="*.ts" --include="*.env" --exclude-dir=node_modules . 2>/dev/null)
+    if [ ! -z "$MATCHES" ]; then
+        echo -e "${RED}✗ Found Risk: Potential secret leakage ($pattern)${NC}"
+        echo "$MATCHES" | sed 's/^/  /'
+        FOUND_SECRETS=$((FOUND_SECRETS + 1))
+    fi
+done
+
+if [ $FOUND_SECRETS -eq 0 ]; then
+    echo -e "${GREEN}✓ No hardcoded secrets detected.${NC}\n"
+else
+    echo -e "${RED}✗ Total secrets found: $FOUND_SECRETS${NC}\n"
+fi
+
+# Summary
+echo -e "${CYAN}----------------------------------------------------${NC}"
+echo -e "${CYAN}   OWASP 2025 Audit Summary                         ${NC}"
+echo -e "${CYAN}----------------------------------------------------${NC}"
+[ $SUPPLY_CHAIN_ISSUES -eq 0 ] && echo -e "A03: Supply Chain        - ${GREEN}PASS${NC}" || echo -e "A03: Supply Chain        - ${RED}FAIL${NC}"
+[ $AUDIT_EXIT -eq 0 ]           && echo -e "A03: Vulnerabilities     - ${GREEN}PASS${NC}" || echo -e "A03: Vulnerabilities     - ${RED}FAIL${NC}"
+[ $FOUND_ISSUES -eq 0 ]        && echo -e "A01/04/05/08: Code Patterns - ${GREEN}PASS${NC}" || echo -e "A01/04/05/08: Code Patterns - ${RED}FAIL${NC}"
+[ $FOUND_EXCEPTION_ISSUES -eq 0 ] && echo -e "A10: Exception Handling  - ${GREEN}PASS${NC}" || echo -e "A10: Exception Handling  - ${RED}FAIL${NC}"
+[ $FOUND_SECRETS -eq 0 ]       && echo -e "A01/A07: Secrets         - ${GREEN}PASS${NC}" || echo -e "A01/A07: Secrets         - ${RED}FAIL${NC}"
+echo -e "${CYAN}----------------------------------------------------${NC}"
+
+if [ $AUDIT_EXIT -eq 0 ] && [ $FOUND_ISSUES -eq 0 ] && [ $FOUND_SECRETS -eq 0 ] && [ $SUPPLY_CHAIN_ISSUES -eq 0 ] && [ $FOUND_EXCEPTION_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}Final Result: SECURE${NC}"
+    exit 0
+else
+    echo -e "${RED}Final Result: VULNERABLE${NC}"
+    exit 1
+fi

package/skills/js-ts-security-skill/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "JS/TS Security",
+  "description": "Verify security of JavaScript and TypeScript codebases against OWASP Top 10 2025 standards",
+  "version": "1.0.0",
+  "author": "AI Agent Skills",
+  "tags": ["javascript", "typescript", "security", "OWASP", "vulnerability-scanning"]
+}

package/skills/skill-creator/claude-code.md

@@ -0,0 +1,66 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+---
+
+# Skill Creator
+
+## Description
+Guide for creating effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations.
+
+## Usage
+Invoke this skill when creating or updating a skill package.
+
+## Instructions
+
+### Skill Creation Process
+
+Follow these steps in order:
+
+1. **Understand** the skill with concrete examples
+2. **Plan** reusable skill contents (scripts, references, assets)
+3. **Initialize** the skill (run `scripts/init_skill.py <name> --path <dir>`)
+4. **Edit** the skill (implement resources, write SKILL.md)
+5. **Package** the skill (run `scripts/package_skill.py <path>`)
+6. **Iterate** based on real usage
+
+### Core Principles
+
+- **Concise is key**: Claude is already smart — only add context it doesn't have. Challenge each piece of information: "Does Claude really need this?"
+- **Appropriate freedom**: Match specificity to task fragility. High freedom for flexible tasks, low freedom for fragile operations.
+- **Progressive disclosure**: Keep SKILL.md under 500 lines. Use references/ for detailed content.
+
+### Skill Structure
+
+```
+skill-name/
+├── SKILL.md (required — YAML frontmatter + markdown body)
+├── scripts/          (executable code, Python/Bash)
+├── references/       (documentation loaded into context as needed)
+└── assets/           (files used in output: templates, images, fonts)
+```
+
+### SKILL.md Frontmatter
+
+Only `name` and `description` are required. Description is the primary trigger mechanism — include both what the skill does AND when to use it.
+
+### Bundled Resources
+
+- **scripts/**: For code that's rewritten repeatedly or needs deterministic reliability
+- **references/**: For documentation Claude should reference while working (schemas, APIs, policies)
+- **assets/**: For files used in output but not loaded into context (templates, images, fonts)
+
+### What NOT to Include
+
+Do NOT create README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, or other auxiliary docs. Only include what an AI agent needs to execute tasks.
+
+### Design Patterns
+
+- **Multi-step processes**: See [references/workflows.md](references/workflows.md)
+- **Output formats**: See [references/output-patterns.md](references/output-patterns.md)
+
+### Tools
+
+- **Initialize**: `scripts/init_skill.py <skill-name> --path <output-dir>`
+- **Validate**: `scripts/quick_validate.py <skill-dir>`
+- **Package**: `scripts/package_skill.py <skill-dir> [output-dir]`