Skip to content

feat: improve skill scores across all examples#23

Merged
shreyas-lyzr merged 1 commit intoopen-gitagent:mainfrom
popey:improve/skill-review-optimization
Mar 16, 2026
Merged

feat: improve skill scores across all examples#23
shreyas-lyzr merged 1 commit intoopen-gitagent:mainfrom
popey:improve/skill-review-optimization

Conversation

@popey
Copy link
Contributor

@popey popey commented Mar 16, 2026

Hullo 👋 @shreyas-lyzr

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

score_card

... and in text form:

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.

Changes made

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%)

How Tested

  • tessl skill review passed on all 9 skills with score improvements
  • YAML frontmatter validates correctly (all skills pass validation checks)
  • No changes to agent.yaml files or directory structure

Checklist

  • My code follows the existing style of this project
  • I have updated documentation (if applicable)
  • I have read the 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 and ask it to optimize your skill. Ping me - @popey - if you hit any snags.

Thanks in advance 🙏

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 🙏
@shreyas-lyzr shreyas-lyzr merged commit abb3674 into open-gitagent:main Mar 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants