feat: improve skill scores across all examples (#23)

Hullo 👋 @shreyas-lyzr

I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:

| Skill | Before | After | Change |
|-------|--------|-------|--------|
| regulatory-analysis | 44% | 94% | +50% |
| code-review | 53% | 94% | +41% |
| export-agent | 55% | 94% | +39% |
| research | 55% | 89% | +34% |
| document-review | 49% | 79% | +30% |
| create-agent | 60% | 90% | +30% |
| run-agent | 60% | 90% | +30% |
| get-started | 66% | 95% | +29% |
| manage-skills | 66% | 94% | +28% |

## What

Improved all 9 example skills across the `examples/` directory — descriptions, trigger terms, concrete examples, and workflow clarity.

## Why

The skill descriptions lacked explicit "Use when..." clauses and specific trigger terms, making it harder for agents to select the right skill. Content was solid but missing concrete examples and validation steps in several cases.

<details>
<summary>Changes made</summary>

**Description improvements (all 9 skills):**
- Added explicit "Use when..." clauses with natural trigger keywords
- Expanded descriptions with specific concrete actions and domain terms
- Switched from vague "Help users..." to third-person action verbs
- Added specific framework/tool names as trigger terms

**Content improvements:**
- `document-review`: Added structured output format with example finding (FINRA 2210 violation)
- `regulatory-analysis`: Added citation validation step and example finding with rule reference
- `create-agent`: Replaced "When to Use" with actionable Quick Start workflow (5 numbered steps)
- `export-agent`: Replaced "When to Use" with export verification step
- `run-agent`: Added troubleshooting section for common authentication errors
- `research`: Added complete example output demonstrating expected quality
- `code-review`: Added example finding with before/after code fix (SQL injection)
- `manage-skills`: Added installation verification step
- `get-started`: Improved description specificity (content already scored 100%)

</details>

## How Tested
- [x] `tessl skill review` passed on all 9 skills with score improvements
- [x] YAML frontmatter validates correctly (all skills pass validation checks)
- [x] No changes to agent.yaml files or directory structure

## Checklist
- [x] My code follows the existing style of this project
- [x] I have updated documentation (if applicable)
- [x] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md)

---

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@popey](https://github.com/popey) - if you hit any snags.

Thanks in advance 🙏

Author: popey

examples/full/skills/document-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document-review
-description: Review financial documents for completeness and compliance
+description: "Reviews financial documents (prospectuses, ADVs, marketing materials) for FINRA 2210 compliance, required disclosures, and balanced presentation. Use when reviewing financial statements, audit documents, regulatory filings, or when the user mentions compliance checks, financial audits, or document verification."
 license: proprietary
 allowed-tools: search-regulations generate-report
 metadata:
@@ -29,3 +29,23 @@ When reviewing a financial document:
 - [ ] Proper disclaimers included
 - [ ] Correct classification (correspondence/retail/institutional)
 - [ ] Principal pre-approval status verified (if retail communication)
+
+## Output Format
+
+For each finding, produce:
+
+```
+### [SEVERITY] — [Rule Reference]
+- **Issue**: [What was found]
+- **Location**: [Section/page reference]
+- **Recommended action**: [Specific fix]
+```
+
+### Example Finding
+
+```
+### WARNING — FINRA 2210(d)(1)(A)
+- **Issue**: Performance claim "consistently outperforms the market" lacks supporting data and time period
+- **Location**: Page 2, paragraph 3
+- **Recommended action**: Add specific time period, benchmark comparison, and standardized performance data per SEC Rule 482
+```

examples/full/skills/regulatory-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: regulatory-analysis
-description: Analyze documents and processes for regulatory compliance
+description: "Analyzes documents and processes against FINRA, SEC, Federal Reserve, and CFPB regulatory frameworks. Identifies compliance gaps, classifies findings by severity, and recommends remediation. Use when performing compliance audits, regulatory reviews, gap analyses, or verifying policy adherence to financial regulations."
 license: proprietary
 allowed-tools: search-regulations
 metadata:
@@ -22,6 +22,7 @@ When analyzing a document or process for regulatory compliance:
 4. **Classify findings** — Rate each finding by severity (CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL)
 5. **Recommend remediation** — Provide specific, actionable steps to address each finding
 6. **Assess confidence** — Rate your confidence in each finding (HIGH, MEDIUM, LOW)
+7. **Validate citations** — Verify all cited rules exist and are current before finalizing
 
 ## Regulatory Priority Order
 When multiple frameworks apply, prioritize in this order:
@@ -66,3 +67,14 @@ When multiple frameworks apply, prioritize in this order:
 ### Disclaimer
 This analysis is for informational purposes only and does not constitute legal advice.
 ```
+
+### Example Finding
+
+```
+#### CRITICAL
+- **Inadequate Suitability Disclosure** — FINRA Rule 2111
+  - Issue: Customer account agreement lacks suitability questionnaire for complex products
+  - Evidence: Section 4.2 references "suitable investments" without defining suitability criteria or risk tolerance assessment
+  - Remediation: Add suitability assessment form per FINRA Rule 2111.05 (Supplementary Material) before account opening
+  - Confidence: HIGH
+```

examples/gitagent-helper/skills/create-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agent
-description: Guide users through agent.yaml configuration, SOUL.md writing, and directory structure
+description: "Creates and configures agent.yaml files, writes SOUL.md personality definitions, and sets up agent directory structures with skills, tools, and knowledge. Use when the user wants to configure an agent, create agent.yaml, write SOUL.md, set up agent directory structure, or customize agent settings."
 license: MIT
 metadata:
   author: gitagent
@@ -10,8 +10,13 @@ metadata:
 
 # Create & Configure Agents
 
-## When to Use
-When a user wants to customize their agent.yaml, write a good SOUL.md, add skills/tools/knowledge, or set up compliance.
+## Quick Start
+
+1. Create directory structure: `mkdir -p my-agent/skills`
+2. Write `agent.yaml` with required fields (see below)
+3. Create `SOUL.md` with agent identity
+4. Add skills, tools, and knowledge as needed
+5. Validate: `gitagent validate -d ./my-agent`
 
 ## agent.yaml Reference
 

examples/gitagent-helper/skills/export-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-agent
-description: Help users export agents to other frameworks and import from existing tools
+description: "Converts agent definitions between frameworks — exports to Claude Code, OpenAI, CrewAI, Lyzr, and GitHub Models formats, and imports from Claude, Cursor, and CrewAI projects. Use when the user wants to convert an agent, migrate to another framework, export to LangChain/AutoGen/CrewAI, or import from existing automation tools."
 license: MIT
 metadata:
   author: gitagent
@@ -10,8 +10,14 @@ metadata:
 
 # Export & Import Agents
 
-## When to Use
-When a user wants to convert their agent to another framework format, or import an existing agent into gitagent.
+## Verify Export
+
+After exporting, check the output matches expectations:
+
+```bash
+# Verify export file was created and contains agent name
+gitagent export -f system-prompt -d ./my-agent | head -5
+```
 
 ## Export
 

examples/gitagent-helper/skills/get-started/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-started
-description: Help users install gitagent and create their first agent from scratch
+description: "Guides installation of gitagent and creation of first agent with scaffolding, configuration, and validation. Use when the user is new to gitagent, asks how to get started, wants to install gitagent, set up their first agent, or says 'how do I start?'"
 license: MIT
 metadata:
   author: gitagent

examples/gitagent-helper/skills/manage-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-skills
-description: Help users search, install, create, and manage agent skills
+description: "Searches the SkillsMP registry, installs skills locally or globally, creates custom skills with SKILL.md frontmatter, and manages the skill lifecycle. Use when the user wants to find skills, add new capabilities, install a skill, browse available skills, create a custom skill, or manage the skills system."
 license: MIT
 metadata:
   author: gitagent
@@ -13,6 +13,14 @@ metadata:
 ## When to Use
 When a user wants to find skills, install them, create new ones, or understand the skills system.
 
+## Verify Installation
+
+After installing a skill, confirm it's available:
+
+```bash
+gitagent skills list -d ./my-agent | grep "code-review"
+```
+
 ## Search Skills
 
 ```bash

examples/gitagent-helper/skills/run-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-agent
-description: Help users run agents with different adapters — Claude, OpenAI, Lyzr, GitHub Models, and more
+description: "Configures and runs agents with different adapters including Claude, OpenAI, CrewAI, Lyzr, and GitHub Models. Supports local execution, remote git repos, and one-shot prompts. Use when the user wants to run an agent, switch LLM providers, configure adapter settings, or launch agents from git repositories."
 license: MIT
 metadata:
   author: gitagent
@@ -13,6 +13,14 @@ metadata:
 ## When to Use
 When a user wants to run an agent locally, from a git repo, or with a specific adapter/framework.
 
+## Troubleshooting
+
+If you see authentication errors:
+- **Claude**: Ensure Claude Code is authenticated (`claude auth status`)
+- **OpenAI**: Verify `OPENAI_API_KEY` is set and valid
+- **GitHub**: Check `GITHUB_TOKEN` has correct permissions
+- **Lyzr**: Confirm `LYZR_API_KEY` is active
+
 ## Basic Usage
 
 ```bash

examples/lyzr-agent/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Research a topic and produce a structured summary with key findings
+description: "Researches a topic by breaking it into subtopics, gathering factual information with reasoning, and producing a structured summary with key findings and open questions. Use when the user asks to research, investigate, look up, summarize a topic, or says 'what is known about...' or 'learn about...'"
 license: MIT
 metadata:
   author: gitagent-examples
@@ -34,3 +34,26 @@ When researching a topic:
 ## Suggested Follow-ups
 - [Related questions the user might want to explore]
 ```
+
+### Example Output
+
+```
+## TL;DR
+WebAssembly (Wasm) is a binary instruction format that enables near-native performance in browsers and increasingly in server-side contexts.
+
+## Research Findings
+
+### Browser Support & Adoption
+- All major browsers support Wasm since 2017 — Chrome, Firefox, Safari, Edge
+- Used in production by Figma (rendering engine), Google Earth (3D), and AutoCAD (web port)
+
+### Performance Characteristics
+- Typically 1.1-1.5x native speed for compute-heavy tasks
+- **Uncertain**: Exact overhead varies significantly by workload type and runtime
+
+## Open Questions
+- How will the component model proposal affect cross-language interop?
+
+## Suggested Follow-ups
+- Compare Wasm vs JavaScript performance for specific use cases
+```

examples/standard/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Review code changes for quality, security, and best practices
+description: "Reviews code diffs and files for security vulnerabilities (OWASP Top 10), error handling, complexity, naming conventions, and performance issues. Use when the user asks to review a PR, pull request, diff, merge request, or code changes."
 license: MIT
 allowed-tools: lint-check complexity-analysis
 metadata:
@@ -40,3 +40,17 @@ When reviewing code:
 ## What's Done Well
 - [Positive observations]
 ```
+
+### Example Finding
+
+```
+### CRITICAL
+- **Line 42**: SQL injection vulnerability — user input concatenated directly into query string.
+  Fix: Use parameterized queries instead of string concatenation.
+  ```python
+  # Before (vulnerable)
+  cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+  # After (safe)
+  cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+  ```
+```