From 6fc2f35d7c200dc7b46dca2ec7f4d1fabe69a111 Mon Sep 17 00:00:00 2001 From: francylisboacharuto Date: Fri, 27 Feb 2026 07:43:50 -0300 Subject: [PATCH] fix: Remove non-standard marketplace.json fields that break Claude Code (fixes #5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Generated skills included activation.keywords, activation.patterns, test_queries, and usage.when_to_use fields in marketplace.json — none of which are supported by Claude Code's official schema. This caused installation failures. Root cause was references/phase4-detection.md instructing the agent to put activation data into marketplace.json instead of the SKILL.md description field. The description is the only activation mechanism. Changes: - Rewrote phase4-detection.md activation section (description-based only) - Removed marketplace.json from stock-analyzer example directory structure - Fixed quality-standards.md checklist reference - Fixed multi-agent-guide.md wording implying marketplace.json has keywords - Deleted marketplace-robust-template.json (source of non-standard fields) - Bumped version to 4.1.0 Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- references/examples/stock-analyzer/SKILL.md | 160 +--- references/multi-agent-guide.md | 2 +- references/phase4-detection.md | 731 ++++-------------- references/quality-standards.md | 2 +- .../marketplace-robust-template.json | 210 ----- 6 files changed, 163 insertions(+), 944 deletions(-) delete mode 100644 references/templates/marketplace-robust-template.json diff --git a/README.md b/README.md index aea29bf..54d5c48 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ **Turn any workflow into reusable AI agent software — no spec writing, no prompt engineering, no coding required.** [![Agent Skills Open Standard](https://img.shields.io/badge/Agent%20Skills-Open%20Standard-blue)](https://github.com/anthropics/agent-skills-spec) -[![Version](https://img.shields.io/badge/version-4.0.0-brightgreen)]() +[![Version](https://img.shields.io/badge/version-4.1.0-brightgreen)]() [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)]() ![Agent Skill Creator Overview](Dynamous/agentskillimage.png) diff --git a/references/examples/stock-analyzer/SKILL.md b/references/examples/stock-analyzer/SKILL.md index 3e569f2..55f64d1 100644 --- a/references/examples/stock-analyzer/SKILL.md +++ b/references/examples/stock-analyzer/SKILL.md @@ -30,144 +30,18 @@ Enable traders and investors to perform technical analysis through natural langu --- -## 🎯 Activation System (3-Layer Architecture) +## Activation -This skill demonstrates the **3-Layer Activation System v3.0** for reliable skill detection. +This skill activates through the `description` field in the SKILL.md frontmatter. The description contains 60+ keywords that enable Claude's natural language understanding to match user queries reliably. -### Layer 1: Keywords (Exact Phrase Matching) +**Key terms embedded in the description:** +- Action verbs: analyze, compare, monitor, track +- Domain entities: stocks, ETFs, tickers +- Specific indicators: RSI, MACD, Bollinger Bands, moving averages +- Use cases: buy/sell signals, comparison, monitoring, chart patterns +- Counter-examples: fundamental analysis, news, options pricing -**Purpose:** High-precision activation for explicit requests - -**Keywords (15 total):** -```json -[ - "analyze stock", // Primary action - "stock analysis", // Alternative phrasing - "technical analysis for", // Domain-specific - "RSI indicator", // Specific indicator 1 - "MACD indicator", // Specific indicator 2 - "Bollinger Bands", // Specific indicator 3 - "buy signal for", // Signal requests - "sell signal for", // Signal requests - "compare stocks", // Comparison action - "stock comparison", // Alternative - "monitor stock", // Monitoring action - "track stock price", // Tracking action - "chart pattern", // Pattern analysis - "moving average for", // Technical indicator - "stock momentum" // Momentum analysis -] -``` - -**Coverage:** -- ✅ Action verbs: analyze, compare, monitor, track -- ✅ Domain entities: stock, ticker, indicator -- ✅ Specific indicators: RSI, MACD, Bollinger -- ✅ Use cases: signals, comparison, monitoring - -### Layer 2: Patterns (Flexible Regex Matching) - -**Purpose:** Capture natural language variations and combinations - -**Patterns (7 total):** - -**Pattern 1: General Stock Analysis** -```regex -(?i)(analyze|analysis)\s+.*\s+(stock|stocks?|ticker|equity|equities)s? -``` -Matches: "analyze AAPL stock", "analysis of tech stocks", "analyze this ticker" - -**Pattern 2: Technical Analysis Request** -```regex -(?i)(technical|chart)\s+(analysis|indicators?)\s+(for|of|on) -``` -Matches: "technical analysis for MSFT", "chart indicators of SPY", "technical analysis on AAPL" - -**Pattern 3: Specific Indicator Request** -```regex -(?i)(RSI|MACD|Bollinger)\s+(for|of|indicator|analysis) -``` -Matches: "RSI for AAPL", "MACD indicator", "Bollinger analysis of TSLA" - -**Pattern 4: Signal Generation** -```regex -(?i)(buy|sell)\s+(signal|recommendation|suggestion)\s+(for|using) -``` -Matches: "buy signal for NVDA", "sell recommendation using RSI", "buy suggestion for AAPL" - -**Pattern 5: Stock Comparison** -```regex -(?i)(compare|comparison|rank)\s+.*\s+stocks?\s+(using|by|with) -``` -Matches: "compare AAPL vs MSFT using RSI", "rank stocks by momentum", "comparison of stocks with MACD" - -**Pattern 6: Monitoring & Tracking** -```regex -(?i)(monitor|track|watch)\s+.*\s+(stock|ticker|price)s? -``` -Matches: "monitor AMZN stock", "track TSLA price", "watch these tickers" - -**Pattern 7: Moving Average & Momentum** -```regex -(?i)(moving average|momentum|volatility)\s+(for|of|analysis) -``` -Matches: "moving average for SPY", "momentum analysis of QQQ", "volatility of AAPL" - -### Layer 3: Description + NLU (Natural Language Understanding) - -**Purpose:** Fallback coverage for edge cases and natural phrasing - -**Enhanced Description (80+ keywords):** -``` -Comprehensive technical analysis tool for stocks and ETFs. Analyzes price movements, -volume patterns, and momentum indicators including RSI (Relative Strength Index), -MACD (Moving Average Convergence Divergence), Bollinger Bands, moving averages, -and chart patterns. Generates buy and sell signals based on technical indicators. -Compares multiple stocks for relative strength analysis. Monitors stock performance -and tracks price alerts. Perfect for traders needing technical analysis, chart -interpretation, momentum tracking, volatility assessment, and comparative stock -evaluation using proven technical analysis methods and trading indicators. -``` - -**Key Terms Included:** -- Action verbs: analyzes, generates, compares, monitors, tracks -- Domain entities: stocks, ETFs, tickers, equities -- Indicators: RSI, MACD, Bollinger Bands, moving averages -- Use cases: buy signals, sell signals, comparison, alerts, monitoring -- Technical terms: momentum, volatility, chart patterns, price movements - -**Coverage:** -- ✅ Primary use case clearly stated upfront -- ✅ All major indicators explicitly mentioned with full names -- ✅ Synonyms and variations included -- ✅ Target user persona defined ("traders") -- ✅ Natural language flow maintained - -### Activation Test Results - -**Layer 1 (Keywords) Test:** -- Tested: 15 keywords × 3 variations = 45 queries -- Success rate: 45/45 = 100% ✅ - -**Layer 2 (Patterns) Test:** -- Tested: 7 patterns × 5 variations = 35 queries -- Success rate: 35/35 = 100% ✅ - -**Layer 3 (Description/NLU) Test:** -- Tested: 10 edge case queries -- Success rate: 9/10 = 90% ✅ - -**Integration Test:** -- Total test queries: 12 -- Activated correctly: 12 -- Success rate: 12/12 = 100% ✅ - -**Negative Test (False Positives):** -- Out-of-scope queries: 7 -- Correctly did not activate: 7 -- Success rate: 7/7 = 100% ✅ - -**Overall Activation Reliability: 98%** (Grade A) +**Activation reliability: 95%+** across tested query variations --- @@ -187,8 +61,7 @@ evaluation using proven technical analysis methods and trading indicators. ``` stock-analyzer/ -├── .claude-plugin/ -│ └── marketplace.json # Activation & metadata +├── SKILL.md # Skill definition and activation (this file) ├── scripts/ │ ├── main.py # Orchestrator │ ├── indicators/ @@ -202,7 +75,6 @@ stock-analyzer/ │ └── utils/ │ └── validators.py # Input validation ├── README.md # User documentation -├── SKILL.md # Technical specification (this file) └── requirements.txt # Dependencies ``` @@ -352,7 +224,7 @@ class SignalGenerator: ## Usage Examples -### when_to_use Cases (from marketplace.json) +### When to Use (from SKILL.md description) 1. ✅ "Analyze AAPL stock using RSI indicator" 2. ✅ "What's the MACD for MSFT right now?" @@ -360,7 +232,7 @@ class SignalGenerator: 4. ✅ "Compare AAPL vs GOOGL using technical analysis" 5. ✅ "Monitor TSLA and alert when RSI is oversold" -### when_not_to_use Cases (from marketplace.json) +### When NOT to Use (from SKILL.md description) 1. ❌ "What's the P/E ratio of AAPL?" → Use fundamental analysis skill 2. ❌ "Latest news about TSLA" → Use news/sentiment skill @@ -510,11 +382,9 @@ matplotlib>=3.7.0 ## References -- **Activation System:** See `phase4-detection.md` -- **Pattern Library:** See `activation-patterns-guide.md` -- **Testing Guide:** See `activation-testing-guide.md` -- **Quality Checklist:** See `activation-quality-checklist.md` -- **Templates:** See `references/templates/` +- **Activation Guide:** See `references/phase4-detection.md` +- **Architecture Guide:** See `references/architecture-guide.md` +- **Quality Standards:** See `references/quality-standards.md` --- diff --git a/references/multi-agent-guide.md b/references/multi-agent-guide.md index 2ea78eb..22d7c93 100644 --- a/references/multi-agent-guide.md +++ b/references/multi-agent-guide.md @@ -377,7 +377,7 @@ The suite structure makes it possible to update the inventory-tracker without to ### Marketplace Discoverability -Each plugin entry in `marketplace.json` has its own description and keywords. This means a suite's individual components can be discovered by different searches: +Each plugin entry in `marketplace.json` has its own `description` field. This means a suite's individual components can be discovered by different searches: - "track sales" finds the sales-monitor plugin - "customer churn" finds the customer-analytics plugin - "inventory alerts" finds the inventory-tracker plugin diff --git a/references/phase4-detection.md b/references/phase4-detection.md index 1f68b2b..3701bb2 100644 --- a/references/phase4-detection.md +++ b/references/phase4-detection.md @@ -648,658 +648,217 @@ work with these records, handle this dataset - [ ] No activation for out-of-scope queries - [ ] Consistent activation across variations -### **🎯 Implementation in Agent-Skill-Creator** +### Implementation in Agent-Skill-Creator **Updated Phase 4 Process:** 1. **Generate base keywords** (traditional method) 2. **Apply systematic expansion** (enhanced method) 3. **Validate coverage** (minimum 50 keywords) -4. **Test natural language** (20+ variations) -5. **Verify activation reliability** (98%+ target) +4. **Embed all keywords into the SKILL.md description field** +5. **Test natural language** (20+ variations) +6. **Verify activation reliability** (98%+ target) -**Template Updates:** -- Enhanced keyword generation in phase4-detection.md -- Expanded pattern libraries in activation-patterns-guide.md -- Rich examples in marketplace-robust-template.json +> **IMPORTANT:** All keywords and activation data go into the SKILL.md `description` field. Do NOT create separate activation files, marketplace.json fields, or pattern files. The description IS the activation mechanism. --- -# 🎯 **Phase 4 Enhanced v3.0: 3-Layer Activation System** +# Phase 4 Enhanced: Description-Based Activation -## Overview: Why 3 Layers? +## How Skill Activation Works -**Problem:** Skills with only description-based activation can: -- Miss valid user queries (false negatives) -- Activate for wrong queries (false positives) -- Be unpredictable across phrasings +The agent (Claude Code, VS Code Copilot, Cursor, etc.) reads the `description` field in SKILL.md frontmatter and uses natural language understanding to decide when to activate the skill. There is no separate activation file, no keywords file, and no regex matching layer. -**Solution:** Implement activation in **3 complementary layers**: +The `description` field is the **only** activation mechanism. A well-crafted description with 50+ embedded keywords achieves 95%+ activation reliability. -``` -Layer 1: Keywords → High precision, moderate coverage -Layer 2: Patterns → High coverage, good precision -Layer 3: Description → Full coverage, Claude NLU fallback -``` - -**Result:** 95%+ activation reliability! +> **CRITICAL:** Do NOT create `activation.keywords`, `activation.patterns`, `test_queries`, `usage.when_to_use`, or `usage.when_not_to_use` fields in marketplace.json or any other file. These are non-standard fields that **break Claude Code installation**. All activation data belongs in the SKILL.md `description` field. --- -## 🔑 Layer 1: Structured Keywords (marketplace.json) -### Purpose -Provide **exact phrase matching** for common, specific queries. +## Writing Effective Descriptions -### Structure in marketplace.json +The description serves all activation purposes — keyword matching and natural language understanding — in a single field. -```json -{ - "activation": { - "keywords": [ - "complete phrase 1", - "complete phrase 2", - "complete phrase 3", - // ... 10-15 total - ] - } -} +### Description Template + +```yaml +description: >- + {Primary use case in one sentence}. Activates for queries about + {capability 1} ({synonyms}), {capability 2} ({synonyms}), and + {capability 3} ({synonyms}). Supports {action verbs}: {action synonyms}. + Uses {technology/API} to {what it does}. Does NOT activate for: + {counter-examples}. ``` +### Description Requirements + +**Must Include:** +- Primary use case clearly stated upfront +- Each capability explicitly mentioned with synonyms in parentheses +- Action verbs the user might say +- Technology/API names +- 3-5 example phrasings embedded naturally +- 2-3 counter-examples (what this skill is NOT for) +- 50+ unique keywords woven into natural prose + +**Length:** 200-500 characters. Longer than typical but necessary for reliable activation. + ### Keyword Design Rules -#### ✅ DO: Use Complete Phrases -```json -✅ "create an agent for" -✅ "analyze stock data" -✅ "compare year over year" +**DO: Use Complete Phrases in the Description** +``` +"technical analysis for stocks" +"analyze stock data" +"buy and sell signals" ``` -#### ❌ DON'T: Use Single Words -```json -❌ "create" // Too generic -❌ "agent" // Too broad -❌ "data" // Meaningless alone +**DON'T: Keyword-Stuff the Description** +``` +"stock RSI MACD Bollinger buy sell signal compare rank" (not prose) ``` -### Keyword Categories (10-15 keywords minimum) +### Embedding Keywords Naturally -**Category 1: Action + Entity (5-7 keywords)** -```json -[ - "create an agent for", - "create a skill for", - "build an agent for", - "develop a skill for", - "make an agent that" -] +Take your keyword research from Steps 1-7 and weave them into coherent prose: + +**Bad (keyword stuffing):** +```yaml +description: "stock analysis RSI MACD Bollinger buy sell signal compare rank chart patterns momentum moving average" ``` -**Category 2: Workflow Patterns (3-5 keywords)** -```json -[ - "automate this workflow", - "automate this process", - "every day I have to", - "daily I need to" -] -``` - -**Category 3: Domain-Specific (2-3 keywords)** -```json -[ - "stock market analysis", // For finance skill - "crop monitoring data", // For agriculture skill - "pdf text extraction" // For document skill -] -``` - -### Keyword Generation Process - -**Step 1:** List all primary capabilities -``` -Skill: us-crop-monitor -Capabilities: -1. Crop condition monitoring -2. Harvest progress tracking -3. Yield data analysis -``` - -**Step 2:** Create 3-4 keywords per capability -``` -Capability 1 → Keywords: -- "crop condition data" -- "crop health monitoring" -- "condition ratings for crops" - -Capability 2 → Keywords: -- "harvest progress report" -- "planting progress data" -- "percent harvested" - -Capability 3 → Keywords: -- "crop yield analysis" -- "productivity data" -- "bushels per acre" -``` - -**Step 3:** Add action variations -``` -- "analyze crop conditions" -- "monitor harvest progress" -- "track planting status" -``` - -**Result:** 10-15 keywords covering main use cases - ---- - -## 🔍 Layer 2: Regex Patterns (marketplace.json) - -### Purpose -Capture **flexible variations** while maintaining specificity. - -### Structure in marketplace.json - -```json -{ - "activation": { - "patterns": [ - "(?i)(verb1|verb2)\\s+.*\\s+(entity|object)", - "(?i)(action)\\s+(context)\\s+(target)", - // ... 5-7 total - ] - } -} -``` - -### Pattern Design Rules - -#### Pattern Anatomy -```regex -(?i) → Case insensitive -(verb1|verb2|verb3) → Action verbs (create, build, make) -\s+ → Whitespace (required) -(an?\s+)? → Optional article (a, an) -(entity) → Target entity -\s+(for|to|that) → Context connector -``` - -### Pattern Categories (5-7 patterns minimum) - -**Pattern 1: Action + Object** -```regex -(?i)(create|build|develop|make)\s+(an?\s+)?(agent|skill)\s+(for|to|that) -``` -Matches: -- "create an agent for" -- "build a skill to" -- "develop agent that" - -**Pattern 2: Automation Request** -```regex -(?i)(automate|automation)\s+(this\s+)?(workflow|process|task|repetitive) -``` -Matches: -- "automate this workflow" -- "automation process" -- "automate task" - -**Pattern 3: Repetitive Workflow** -```regex -(?i)(every day|daily|repeatedly)\s+(I|we)\s+(have to|need to|do|must) -``` -Matches: -- "every day I have to" -- "daily we need to" -- "repeatedly I must" - -**Pattern 4: Transformation** -```regex -(?i)(turn|convert|transform)\s+(this\s+)?(process|workflow|task)\s+into\s+(an?\s+)?agent -``` -Matches: -- "turn this process into an agent" -- "convert workflow to agent" -- "transform task into agent" - -**Pattern 5: Domain-Specific** -```regex -(?i)(analyze|analysis|monitor|track)\s+.*\s+(crop|stock|customer|data) -``` -Matches: -- "analyze crop conditions" -- "monitor stock performance" -- "track customer behavior" - -**Pattern 6-7:** Add more based on specific skill needs - -### Pattern Testing - -**Test each pattern independently:** - -```markdown -Pattern: (?i)(create|build)\s+(an?\s+)?agent\s+for - -Test queries: -✅ "create an agent for processing PDFs" -✅ "build agent for data analysis" -✅ "Create a Agent For automation" -❌ "I want to create something" // No "agent" -❌ "agent creation guide" // No action verb -``` - -### Common Regex Components - -**Verbs - Action:** -```regex -(create|build|develop|make|generate|design) -(analyze|analysis|monitor|track|measure) -(compare|rank|sort|list|show) -(automate|automation|streamline) -``` - -**Entities:** -```regex -(agent|skill|workflow|process|task) -(crop|stock|customer|product|invoice) -(data|report|dashboard|analysis) -``` - -**Connectors:** -```regex -(for|to|that|with|using|from) -(about|on|regarding|concerning) +**Good (natural prose with keywords embedded):** +```yaml +description: >- + Provides comprehensive technical analysis for stocks and ETFs using RSI + (Relative Strength Index), MACD (Moving Average Convergence Divergence), + Bollinger Bands, moving averages, and chart patterns. Generates buy and + sell signals based on technical indicator combinations. Compares and ranks + multiple stocks by momentum and technical strength. Does NOT activate for + fundamental analysis (P/E ratios, earnings), news, or options pricing. ``` --- -## 📝 Layer 3: Description + NLU (Existing, Enhanced) +## Complete Example: stock-analyzer -### Purpose -Provide **Claude-interpretable** context for cases not covered by keywords/patterns. - -### Enhanced Description Template +### SKILL.md Frontmatter (the ONLY activation mechanism) ```yaml -description: | - This skill should be used when the user {primary use case}. - - Activates for queries about: - - {capability 1} ({synonyms, keywords}) - - {capability 2} ({synonyms, keywords}) - - {capability 3} ({synonyms, keywords}) - - Supports {actions list}: {action synonyms}. - - Uses {technology/API} to {what it does}. - - Examples: {example queries}. - - Does NOT activate for: {counter-examples}. +--- +name: stock-analyzer +description: >- + Provides comprehensive technical analysis for stocks and ETFs using RSI + (Relative Strength Index), MACD (Moving Average Convergence Divergence), + Bollinger Bands, moving averages, and chart patterns. Generates buy and + sell signals based on technical indicator combinations. Compares multiple + stocks and ranks them by momentum and technical strength. Monitors stock + performance and tracks price alerts. Activates when user asks to analyze + stocks, calculate technical indicators, get trading signals, compare + tickers, or assess market momentum. Does NOT activate for fundamental + analysis (P/E ratios, earnings), news-based analysis, portfolio + optimization, or options pricing. +version: 1.0.0 +license: MIT +metadata: + author: finance-team + version: 1.0.0 +--- ``` -### Enhanced Requirements +**Why this achieves 95%+ activation:** +- Contains 60+ unique keywords naturally embedded +- All capabilities mentioned with synonyms +- Action verbs match how users phrase requests +- Counter-examples prevent false positives +- Technical terms (RSI, MACD, Bollinger) enable precise matching +- General terms ("technical analysis", "trading signals") catch broad queries -**Must Include:** -- ✅ All 60+ keywords from Step 2.5 -- ✅ Each capability explicitly mentioned -- ✅ Synonyms in parentheses -- ✅ Technology/API names -- ✅ 3-5 example queries -- ✅ 2-3 counter-examples +### Testing the Description -**Length:** 300-500 characters (yes, longer than typical!) +**Positive Tests (should activate):** +``` +1. "Analyze AAPL stock using RSI" -> activates +2. "What's the MACD for Tesla?" -> activates +3. "Show me buy signals for tech stocks" -> activates +4. "Compare AAPL vs GOOGL using technical analysis" -> activates +5. "Moving average crossover for SPY" -> activates +6. "Bollinger Bands analysis for Bitcoin" -> activates +7. "Is TSLA overbought based on RSI?" -> activates +8. "Chart patterns for NVDA" -> activates +9. "Momentum indicators for tech stocks" -> activates +10. "Track AMZN for MACD crossover signals" -> activates +``` + +**Negative Tests (should NOT activate):** +``` +1. "What's the P/E ratio of AAPL?" -> fundamental, not technical +2. "Latest news about TSLA?" -> news, not analysis +3. "Execute a buy order for NVDA" -> brokerage, not analysis +4. "Options strategies for AAPL" -> options, not indicators +``` --- -## ✅ Step 8: Validation & Testing (NEW) +## Validation & Testing -### Testing Requirements +### Testing Process **Minimum Test Coverage:** - 10+ query variations per major capability -- All test queries documented in marketplace.json +- Document all test queries in your SKILL.md body (under a Testing section) - Manual testing of each variation - No false positives in counter-examples -### Test Query Structure in marketplace.json +### Improving Activation Reliability -```json -{ - "test_queries": [ - "Query variation 1 (tests keyword X)", - "Query variation 2 (tests pattern Y)", - "Query variation 3 (tests description)", - "Query variation 4 (natural phrasing)", - "Query variation 5 (shortened form)", - "Query variation 6 (verbose form)", - "Query variation 7 (domain synonym)", - "Query variation 8 (action synonym)", - "Query variation 9 (multilingual variant)", - "Query variation 10 (edge case)" - ] -} -``` +If a test query fails to activate the skill: + +1. **Check if the query's key terms appear in the description.** If "momentum" isn't there but users ask about momentum, add it. +2. **Add synonyms in parentheses.** If users say "technical indicators" but the description only says "RSI, MACD", add the general term too. +3. **Add counter-examples.** If the skill activates for wrong queries, add "Does NOT activate for: {those cases}" to the description. ### Validation Checklist ```markdown -## Layer 1: Keywords Validation -- [ ] 10-15 keywords defined? -- [ ] Keywords are complete phrases (not single words)? -- [ ] Keywords cover main use cases? -- [ ] No overly generic keywords? +## Description Quality +- [ ] Primary use case stated upfront? +- [ ] All capabilities mentioned with synonyms? +- [ ] 50+ unique keywords embedded as natural prose? +- [ ] Action verbs included? +- [ ] Counter-examples documented? +- [ ] 200-500 characters length? -## Layer 2: Patterns Validation -- [ ] 5-7 patterns defined? -- [ ] Patterns require action verbs? -- [ ] Patterns tested independently? -- [ ] No overly broad patterns? - -## Layer 3: Description Validation -- [ ] 60+ unique keywords included? -- [ ] All capabilities mentioned? -- [ ] Synonyms provided? -- [ ] Counter-examples listed? - -## Integration Testing -- [ ] 10+ test queries per capability? -- [ ] All test queries activate skill? -- [ ] Counter-examples don't activate? -- [ ] No conflicts with other skills? -``` - -### Test Report Template - -```markdown -## Activation Test Report - -**Skill:** {skill-name} -**Date:** {date} -**Tester:** {name} - -### Test Results - -**Keywords (Layer 1):** -- Total keywords: {count} -- Tested: {count} -- Pass rate: {X/Y}% - -**Patterns (Layer 2):** -- Total patterns: {count} -- Tested: {count} -- Pass rate: {X/Y}% - -**Test Queries:** -- Total test queries: {count} -- Activated correctly: {count} -- False negatives: {count} -- False positives: {count} - -### Issues Found -1. {Issue description} -2. {Issue description} - -### Recommendations -1. {Recommendation} -2. {Recommendation} +## Testing +- [ ] 10+ positive test queries per capability? +- [ ] All test queries activate the skill? +- [ ] Negative test queries do NOT activate? +- [ ] No false positives found? +- [ ] No false negatives found? ``` --- -## 🎯 Complete Example: Robust Detection Implementation +## Final Phase 4 Checklist -### Example Skill: stock-analyzer -**marketplace.json:** - -```json -{ - "name": "stock-analyzer", - "description": "Technical stock analysis using indicators", - - "activation": { - "keywords": [ - "analyze stock", - "stock technical analysis", - "RSI for stocks", - "MACD analysis", - "moving average crossover", - "Bollinger Bands", - "buy sell signals", - "technical indicators", - "chart patterns", - "stock momentum" - ], - - "patterns": [ - "(?i)(analyze|analysis)\\s+.*\\s+(stock|stocks|ticker|equity)", - "(?i)(technical|chart)\\s+(analysis|indicators?)\\s+(for|of)", - "(?i)(RSI|MACD|moving average|Bollinger|momentum)\\s+(for|of|analysis)", - "(?i)(buy|sell)\\s+(signal|signals|recommendation)\\s+(for|using)", - "(?i)(compare|rank)\\s+.*\\s+stocks?\\s+(using|with|by)" - ] - }, - - "usage": { - "example": "Analyze AAPL using RSI and MACD indicators", - "when_to_use": [ - "User asks for technical stock analysis", - "User wants to analyze indicators (RSI, MACD, etc.)", - "User needs buy/sell signals based on technicals", - "User wants to compare stocks using technical metrics" - ], - "when_not_to_use": [ - "Fundamental analysis (P/E ratios, earnings)", - "News-based analysis", - "Portfolio optimization", - "Options pricing" - ] - }, - - "test_queries": [ - "Analyze AAPL stock using RSI", - "What's the MACD for Tesla?", - "Show me technical indicators for MSFT", - "Buy or sell signals for Google stock?", - "Moving average crossover for SPY", - "Bollinger Bands analysis for Bitcoin", - "Compare technical strength of AAPL vs MSFT", - "Is TSLA overbought based on RSI?", - "Chart patterns for NVDA", - "Momentum indicators for tech stocks" - ] -} -``` - ---- - -## 📋 Final Phase 4 Checklist (Enhanced v3.0) - -### Traditional Detection (Steps 1-7) -- [ ] Entities listed -- [ ] Actions/verbs listed +### Keyword Research (Steps 1-7) +- [ ] Domain entities listed (organizations, objects, metrics) +- [ ] Action verbs listed (analyze, compare, monitor, track) +- [ ] 50+ keywords generated via systematic expansion - [ ] Question variations mapped - [ ] Negative scope defined -- [ ] Description created -- [ ] Keywords documented -### Layer 1: Keywords -- [ ] 10-15 keywords defined -- [ ] Keywords are complete phrases -- [ ] Keywords categorized (action, workflow, domain) -- [ ] Keywords added to marketplace.json - -### Layer 2: Patterns -- [ ] 5-7 regex patterns defined -- [ ] Patterns require action verbs + context -- [ ] Each pattern tested individually -- [ ] Patterns added to marketplace.json - -### Layer 3: Description -- [ ] 60+ unique keywords included +### Description Writing +- [ ] All keywords embedded into SKILL.md `description` as natural prose +- [ ] Primary use case stated upfront - [ ] All capabilities mentioned with synonyms -- [ ] Example queries provided -- [ ] Counter-examples documented +- [ ] Counter-examples documented ("Does NOT activate for") +- [ ] 200-500 characters length -### Testing & Validation -- [ ] 10+ test queries per capability -- [ ] All queries added to test_queries array -- [ ] Manual testing completed -- [ ] No false positives/negatives found -- [ ] Test report documented - -### Integration -- [ ] when_to_use / when_not_to_use defined -- [ ] No conflicts with other skills identified -- [ ] Activation priority appropriate -- [ ] Documentation complete +### Testing +- [ ] 10+ positive test queries per capability +- [ ] Negative test queries for out-of-scope requests +- [ ] All test queries activate correctly +- [ ] Counter-examples correctly do NOT activate +- [ ] No false positives found --- - -## 💡 Quick Reference: 3-Layer Activation Checklist - -```markdown -✅ **Layer 1: Keywords** (10-15 keywords) - - Complete phrases (not single words) - - Cover main use cases - - Categorized by type - -✅ **Layer 2: Patterns** (5-7 regex) - - Require action verbs - - Flexible but specific - - Tested independently - -✅ **Layer 3: Description** (300-500 chars) - - 60+ unique keywords - - All capabilities mentioned - - Examples + counter-examples - -✅ **Testing** (10+ variations) - - All test queries activate - - No false positives - - Documented results -``` - -**Remember:** More layers = More reliability = Happier users! - ---- - -## 🧠 **NEW: Context-Aware Detection (Layer 4)** - -### **Enhanced 4-Layer Detection System** - -The Agent-Skill-Creator v3.1 now includes a fourth layer for context-aware filtering, making the system **4-Layer Detection**: - -``` -Layer 1: Keywords → Direct keyword matching -Layer 2: Patterns → Regex pattern matching -Layer 3: Description + NLU → Semantic understanding -Layer 4: Context-Aware → Contextual filtering (NEW) -``` - -### **Context-Aware Detection Process** - -#### **Step 4A: Context Extraction** -1. **Domain Context**: Identify primary and secondary domains -2. **Task Context**: Determine user's current task and stage -3. **Intent Context**: Extract primary and secondary intents -4. **Conversational Context**: Analyze conversation history and coherence - -#### **Step 4B: Context Relevance Analysis** -1. **Domain Relevance**: Match query domains with skill's expected domains -2. **Task Relevance**: Match user tasks with skill's supported tasks -3. **Capability Relevance**: Match required capabilities with skill's capabilities -4. **Context Coherence**: Evaluate conversation consistency - -#### **Step 4C: Negative Context Detection** -1. **Excluded Domains**: Check for explicitly excluded domains -2. **Conflicting Intents**: Identify conflicting user intents -3. **Inappropriate Contexts**: Detect tutorial, help, or debugging contexts -4. **Resource Constraints**: Check for unavailable resources or permissions - -#### **Step 4D: Context-Aware Decision** -1. **Relevance Scoring**: Calculate weighted context relevance score -2. **Threshold Comparison**: Compare against confidence thresholds -3. **Negative Filtering**: Apply negative context filters -4. **Final Decision**: Make context-aware activation decision - -### **Context-Aware Configuration** - -```json -{ - "activation": { - "keywords": [...], - "patterns": [...], - - "_comment": "Context-aware filtering (v1.0)", - "contextual_filters": { - "required_context": { - "domains": ["finance", "trading"], - "tasks": ["analysis", "calculation"], - "confidence_threshold": 0.8 - }, - "excluded_context": { - "domains": ["education", "tutorial"], - "tasks": ["help", "explanation"] - }, - "activation_rules": { - "min_relevance_score": 0.75, - "max_negative_score": 0.3 - } - } - } -} -``` - -### **Context Testing Examples** - -**Positive Context (Should Activate):** -```json -{ - "query": "Analyze AAPL stock using RSI indicator", - "context": { - "domain": "finance", - "task": "analysis", - "intent": "analyze" - }, - "expected": true, - "reason": "Perfect domain and task match" -} -``` - -**Negative Context (Should NOT Activate):** -```json -{ - "query": "Explain what stock analysis is", - "context": { - "domain": "education", - "task": "explanation", - "intent": "learn" - }, - "expected": false, - "reason": "Educational context, not task execution" -} -``` - -### **Context-Aware Validation Checklist** - -```markdown -## Layer 4: Context-Aware Validation -- [ ] Required domains defined in contextual_filters? -- [ ] Excluded domains defined to prevent false positives? -- [ ] Confidence thresholds set appropriately? -- [ ] Context weights configured for domain needs? -- [ ] Negative context rules implemented? -- [ ] Context test cases generated and validated? -- [ ] False positive rate measured <1%? -- [ ] Context analysis time <100ms? -``` - -### **Expected Performance Improvements** - -- **False Positive Rate**: 2% → **<1%** -- **Context Precision**: 60% → **85%** -- **User Satisfaction**: 85% → **95%** -- **Overall Reliability**: 98% → **99.5%** - -**Enhanced Remember:** 4 Layers = Maximum Reliability = Exceptional UX! diff --git a/references/quality-standards.md b/references/quality-standards.md index 94f4dc1..dc14153 100644 --- a/references/quality-standards.md +++ b/references/quality-standards.md @@ -636,7 +636,7 @@ Ask questions about agriculture and the agent will respond. - [ ] **CHANGELOG.md** created with complete v1.0.0 entry - [ ] **INSTALACAO.md** with complete didactic tutorial - [ ] **comprehensive_{domain}_report()** implemented -- [ ] marketplace.json with version field +- [ ] SKILL.md with version in frontmatter metadata - [ ] 18+ files created - [ ] ~1500+ lines of Python code - [ ] ~10,000+ words of documentation diff --git a/references/templates/marketplace-robust-template.json b/references/templates/marketplace-robust-template.json deleted file mode 100644 index 56a61c9..0000000 --- a/references/templates/marketplace-robust-template.json +++ /dev/null @@ -1,210 +0,0 @@ -{ - "_comment": "Robust Activation Template - Replace all {{placeholders}} with actual values", - - "name": "{{skill-name}}", - "owner": { - "name": "Agent Creator", - "email": "noreply@example.com" - }, - - "metadata": { - "description": "{{Brief 1-2 sentence description of what the skill does}}", - "version": "1.0.0", - "created": "{{YYYY-MM-DD}}", - "updated": "{{YYYY-MM-DD}}", - "language": "en-US", - "features": [ - "{{feature-1}}", - "{{feature-2}}", - "{{feature-3}}" - ] - }, - - "plugins": [ - { - "name": "{{skill-name}}-plugin", - "description": "{{Comprehensive description with all capabilities, keywords, and use cases - 300-500 characters}}", - "source": "./", - "strict": false, - "skills": ["./"] - } - ], - - "activation": { - "_comment": "Layer 1: Enhanced keywords (50-80 keywords for 98% reliability)", - "keywords": [ - "_comment": "Category 1: Core capabilities (10-15 keywords)", - "{{action-1}} {{entity}}", - "{{action-1}} {{entity}} and {{action-2}}", - "{{action-2}} {{entity}}", - "{{action-2}} {{entity}} and {{action-1}}", - "{{action-3}} {{entity}}", - "{{action-3}} {{entity}} and {{action-4}}", - - "_comment": "Category 2: Synonym variations (10-15 keywords)", - "{{synonym-1-verb}} {{entity}}", - "{{synonym-1-verb}} {{entity}} {{synonym-1-object}}", - "{{synonym-2-verb}} {{entity}}", - "{{synonym-3-verb}} {{entity}} {{synonym-3-object}}", - "{{domain-technical-term}}", - "{{domain-business-term}}", - - "_comment": "Category 3: Direct variations (8-12 keywords)", - "{{action-1}} {{entity}} from {{source-type}}", - "{{action-2}} {{entity}} from {{source-type}}", - "{{action-3}} {{entity}} in {{context}}", - "{{workflow-phrase-1}}", - "{{workflow-phrase-2}}", - "{{workflow-phrase-3}}", - "{{workflow-phrase-4}}", - - "_comment": "Category 4: Domain-specific (5-8 keywords)", - "{{domain-specific-phrase-1}}", - "{{domain-specific-phrase-2}}", - "{{domain-specific-phrase-3}}", - "{{domain-technical-phrase}}", - "{{domain-business-phrase}}", - - "_comment": "Category 5: Natural language (5-10 keywords)", - "how to {{action-1}} {{entity}}", - "what can I {{action-1}} {{entity}}", - "can you {{action-2}} {{entity}}", - "help me {{action-3}} {{entity}}", - "I need to {{action-1}} {{entity}}", - "{{entity}} from this {{source-type}}" - "{{entity}} from the {{source-type}}" - "get {{domain-object}} {{context}}" - "process {{domain-object}} here" - "work with these {{domain-objects}}" - ], - - "_comment": "Layer 2: Enhanced pattern matching (10-15 patterns for 98% coverage)", - "patterns": [ - "_comment": "Pattern 1: Enhanced data extraction", - "(?i)(extract|scrape|get|pull|retrieve|harvest|collect|obtain)\\s+(and\\s+)?(analyze|process|handle|work\\s+with|examine|study|evaluate)\\s+(data|information|content|details|records|dataset|metrics)\\s+(from|on|of|in)\\s+(website|site|url|webpage|api|database|file|source)", - - "_comment": "Pattern 2: Enhanced data processing", - "(?i)(analyze|process|handle|work\\s+with|examine|study|evaluate|review|assess|explore|investigate|scrutinize)\\s+(web|online|site|website|digital)\\s+(data|information|content|metrics|records|dataset)", - - "_comment": "Pattern 3: Enhanced normalization", - "(?i)(normalize|clean|format|standardize|structure|organize)\\s+(extracted|web|scraped|collected|gathered|pulled|retrieved)\\s+(data|information|content|records|metrics|dataset)", - - "_comment": "Pattern 4: Enhanced workflow automation", - "(?i)(every|daily|weekly|monthly|regularly|constantly|always)\\s+(I|we)\\s+(have to|need to|must|should|got to)\\s+(extract|process|handle|work\\s+with|analyze|manage|deal\\s+with)\\s+(data|information|reports|metrics|records)", - - "_comment": "Pattern 5: Enhanced transformation", - "(?i)(turn|convert|transform|change|modify|update|convert)\\s+(this\\s+)?({{source}})\\s+into\\s+(an?\\s+)?({{target}})", - - "_comment": "Pattern 6: Technical operations", - "(?i)(web\\s+scraping|data\\s+mining|API\\s+integration|ETL\\s+process|data\\s+extraction|content\\s+parsing|information\\s+retrieval|data\\s+processing)\\s+(for|of|to|from)\\s+(website|site|api|database|source)", - - "_comment": "Pattern 7: Business operations", - "(?i)(process\\s+business\\s+data|handle\\s+reports|analyze\\s+metrics|work\\s+with\\s+datasets|manage\\s+information|extract\\s+insights|normalize\\s+business\\s+records)\\s+(for|in|from)\\s+(reports|analytics|dashboard|meetings)", - - "_comment": "Pattern 8: Natural language questions", - "(?i)(how\\s+to|what\\s+can\\s+I|can\\s+you|help\\s+me|I\\s+need\\s+to)\\s+(extract|get|pull|scrape|analyze|process|handle)\\s+(data|information|content)\\s+(from|on|of)\\s+(this|that|the)\\s+(website|site|page|source)", - - "_comment": "Pattern 9: Conversational commands", - "(?i)(extract|get|scrape|pull|retrieve|collect|harvest)\\s+(data|information|content|details|metrics|records)\\s+(from|on|of|in)\\s+(this|that|the)\\s+(website|site|webpage|api|file|source)", - - "_comment": "Pattern 10: Domain-specific action", - "(?i)({{domain-verb1}}|{{domain-verb2}}|{{domain-verb3}}|{{domain-verb4}}|{{domain-verb5}})\\s+.*\\s+({{domain-entity1}}|{{domain-entity2}}|{{domain-entity3}})" - ] - }, - - "_comment": "NEW: Context-aware activation filters (v1.0)", - "contextual_filters": { - "required_context": { - "domains": ["{{primary-domain}}", "{{secondary-domain-1}}", "{{secondary-domain-2}}"], - "tasks": ["{{primary-task}}", "{{secondary-task-1}}", "{{secondary-task-2}}"], - "entities": ["{{primary-entity}}", "{{secondary-entity-1}}", "{{secondary-entity-2}}"], - "confidence_threshold": 0.8 - }, - - "excluded_context": { - "domains": ["{{excluded-domain-1}}", "{{excluded-domain-2}}", "{{excluded-domain-3}}"], - "tasks": ["{{excluded-task-1}}", "{{excluded-task-2}}"], - "query_types": ["{{excluded-query-type-1}}", "{{excluded-query-type-2}}"], - "user_states": ["{{excluded-user-state-1}}", "{{excluded-user-state-2}}"] - }, - - "context_weights": { - "domain_relevance": 0.35, - "task_relevance": 0.30, - "intent_strength": 0.20, - "conversation_coherence": 0.15 - }, - - "activation_rules": { - "min_relevance_score": 0.75, - "max_negative_score": 0.3, - "required_coherence": 0.6, - "context_consistency_check": true - } - }, - - "capabilities": { - "{{capability-1}}": true, - "{{capability-2}}": true, - "{{capability-3}}": true, - "context_requirements": { - "min_confidence": 0.8, - "required_domains": ["{{primary-domain}}"], - "supported_tasks": ["{{primary-task}}", "{{secondary-task-1}}"] - } - }, - - "usage": { - "example": "{{Concrete example query that should activate this skill}}", - - "input_types": [ - "{{input-type-1}}", - "{{input-type-2}}", - "{{input-type-3}}" - ], - - "output_types": [ - "{{output-type-1}}", - "{{output-type-2}}" - ], - - "_comment": "When to use this skill", - "when_to_use": [ - "{{use-case-1}}", - "{{use-case-2}}", - "{{use-case-3}}", - "{{use-case-4}}", - "{{use-case-5}}" - ], - - "_comment": "When NOT to use this skill (prevent false positives)", - "when_not_to_use": [ - "{{counter-case-1}}", - "{{counter-case-2}}", - "{{counter-case-3}}" - ] - }, - - "test_queries": [ - "_comment": "10+ variations to test activation", - "{{test-query-1 - tests keyword X}}", - "{{test-query-2 - tests pattern Y}}", - "{{test-query-3 - tests description}}", - "{{test-query-4 - natural phrasing}}", - "{{test-query-5 - shortened form}}", - "{{test-query-6 - verbose form}}", - "{{test-query-7 - domain synonym}}", - "{{test-query-8 - action synonym}}", - "{{test-query-9 - edge case}}", - "{{test-query-10 - real-world example}}" - ], - - "_instructions": { - "step_1": "Replace ALL {{placeholders}} with actual values", - "step_2": "Remove all _comment fields before deploying", - "step_3": "Test all keywords and patterns independently", - "step_4": "Run full test suite with test_queries", - "step_5": "Verify 95%+ activation success rate", - "step_6": "Document any issues and iterate" - } -}