| docs(examples): improve skill scores across 8 skills (#1809)
Hullo @mdrxy 👋
I ran your skills through tessl skill review at work and found some
targeted improvements. The process was run by me, a human meatbag (yes,
I am typing, and that's me (with shorter hair) in the avatar), with some
assistance from a skill and claude, which feels fitting and somewhat
meta, given it's measuring and updating some skills. So I would consider
this a clear disclaimer that I have used AI, but I did human write this.
This is done with good intent, not to land some slop, the goal is to
improve the activation and use of the skills you're sharing here, that's
all. 🙏
<!-- Replace everything above this line with a 1-2 sentence description
of your change. Keep the "Fixes #xx" keyword and update the issue
number. -->
<img width="1312" height="1214" alt="deepagents_score_card"
src="https://github.com/user-attachments/assets/2fbd8b01-b73a-40d9-96b4-2047eb5c4004"
/>
Here's the before/after:
| Skill | Before | After | Change |
|-------|--------|-------|--------|
| query-writing | 53% | 100% | +47% |
| arxiv-search | 52% | 94% | +42% |
| blog-post | 59% | 89% | +30% |
| social-media | 59% | 89% | +30% |
| langgraph-docs | 56% | 86% | +30% |
| web-research | 59% | 89% | +30% |
| schema-exploration | 55% | 83% | +28% |
| skill-creator (built-in) | 84% | 88% | +4% |
<details>
<summary>What changed</summary>
**Description improvements (all skills)**
- Added concrete action verbs to frontmatter descriptions (e.g. "Writes
and structures long-form blog posts" instead of just "Use this skill
when writing...")
- Added explicit "Use when..." clauses with natural trigger terms users
would actually say
- Expanded trigger term coverage (e.g. "tweet", "thread", "caption" for
social-media)
**Body conciseness (7 skills)**
- Removed redundant "When to Use This Skill" body sections — these are
only read after triggering, so they waste context tokens
- Removed filler intro sentences ("This skill provides a structured
workflow for...")
- Removed "Available Tools" and "Research Subagent Configuration"
sections from web-research — the agent already knows its tools
- Removed verbose "Common Exploration Patterns" and "Tips" sections from
schema-exploration that restated earlier content
- Trimmed "About Skills" and "What Skills Provide" sections from both
skill-creator instances
**arxiv-search (52% → 94%)**
- Replaced 103 lines of verbose content with 34 focused lines
- Removed explanations of what arXiv is, "When to Use" section,
"Features" list, and "Notes" section
- Kept only the essential: usage syntax, one example, and dependency
install
**langgraph-docs (56% → 86%)**
- Added concrete capabilities to description (stateful agents,
multi-agent workflows, human-in-the-loop)
- Added error recovery guidance for failed fetch_url calls
- Removed redundant "Overview" section
**query-writing (53% → 100%)**
- Added error recovery section for empty results, syntax errors, and
timeouts
</details>
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 🙏
> **Disclaimer**: This contribution was assisted by generative AI
tooling (Claude Code + tessl skill review).
## make format
```
make format
🎨 Formatting libs/acp
[ "deepagents_acp/ tests/" = "" ] || uv run --group test ruff format deepagents_acp/ tests/
Using CPython 3.12.11
Creating virtual environment at: .venv
Built deepagents-acp @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/acp
Installed 69 packages in 100ms
11 files left unchanged
[ "deepagents_acp/ tests/" = "" ] || uv run --group test ruff check --fix deepagents_acp/ tests/
All checks passed!
🎨 Formatting libs/cli
[ "." = "" ] || uv run --all-groups ruff format .
Using CPython 3.12.11
Creating virtual environment at: .venv
Built deepagents-cli @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/cli
Built deepagents @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/deepagents
Installed 177 packages in 213ms
125 files left unchanged
[ "." = "" ] || uv run --all-groups ruff check --fix .
All checks passed!
🎨 Formatting libs/deepagents
[ "." = "" ] || uv run --all-groups ruff format .
Using CPython 3.12.11
Creating virtual environment at: .venv
Installed 118 packages in 143ms
80 files left unchanged
[ "." = "" ] || uv run --all-groups ruff check --fix .
All checks passed!
🎨 Formatting libs/harbor
[ "deepagents_harbor/ tests/" = "" ] || uv run --group test ruff format deepagents_harbor/ tests/
Using CPython 3.12.11
Creating virtual environment at: .venv
Built deepagents-cli @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/cli
Built deepagents-harbor @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/harbor
Installed 198 packages in 390ms
7 files left unchanged
[ "deepagents_harbor/ tests/" = "" ] || uv run --group test ruff check --fix deepagents_harbor/ tests/
All checks passed!
🎨 Formatting libs/partners/daytona
[ "." = "" ] || uv run --all-groups ruff format .
Using CPython 3.12.11
Creating virtual environment at: .venv
Built langchain-daytona @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/partners/daytona
Installed 115 packages in 133ms
8 files left unchanged
[ "." = "" ] || uv run --all-groups ruff check --fix .
All checks passed!
🎨 Formatting libs/partners/modal
[ "." = "" ] || uv run --all-groups ruff format .
Using CPython 3.12.11
Creating virtual environment at: .venv
Built langchain-modal @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/partners/modal
Installed 102 packages in 97ms
8 files left unchanged
[ "." = "" ] || uv run --all-groups ruff check --fix .
All checks passed!
🎨 Formatting libs/partners/runloop
[ "." = "" ] || uv run --all-groups ruff format .
Using CPython 3.12.11
Creating virtual environment at: .venv
Built langchain-runloop @ file:///Users/alan/Projects/auto-p-o/langchain-ai/deepagents/libs/partners/runloop
Installed 79 packages in 72ms
8 files left unchanged
[ "." = "" ] || uv run --all-groups ruff check --fix .
All checks passed!
✅ All packages formatted!
```
## make lint
```
make lint
🔍 Linting libs/acp
[ "deepagents_acp/ tests/" = "" ] || uv run --group test ruff format deepagents_acp/ tests/ --diff
11 files already formatted
[ "deepagents_acp/ tests/" = "" ] || uv run --group test ruff check deepagents_acp/ tests/
All checks passed!
/Library/Developer/CommandLineTools/usr/bin/make type
uv run --group test ty check deepagents_acp
All checks passed!
🔍 Linting libs/cli
[ "." = "" ] || uv run --all-groups ruff check .
All checks passed!
[ "." = "" ] || uv run --all-groups ruff format . --diff
125 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type PYTHON_FILES="."
uv run --all-groups ty check .
warning[possibly-missing-attribute]: Attribute kwargs may be missing on object of type _Call | None | @Todo
--> tests/unit_tests/test_thread_selector.py:1409:22
|
1408 | mock_list_threads.assert_awaited_once()
1409 | kw = mock_list_threads.await_args.kwargs
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1410 | assert kw["limit"] == 20
1411 | assert kw["include_message_count"] is False
|
info: rule possibly-missing-attribute is enabled by default
warning[possibly-missing-attribute]: Attribute kwargs may be missing on object of type _Call | None | @Todo
--> tests/unit_tests/test_thread_selector.py:1501:22
|
1500 | mock_list_threads.assert_awaited_once()
1501 | kw = mock_list_threads.await_args.kwargs
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1502 | assert kw["limit"] == 20
1503 | assert kw["include_message_count"] is False
|
info: rule possibly-missing-attribute is enabled by default
Found 2 diagnostics
🔍 Linting libs/deepagents
[ "." = "" ] || uv run --all-groups ruff check .
All checks passed!
[ "." = "" ] || uv run --all-groups ruff format . --diff
80 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type
uv run --all-groups ty check deepagents
All checks passed!
🔍 Linting libs/harbor
[ "deepagents_harbor/ tests/" = "" ] || uv run --group test ruff format deepagents_harbor/ tests/ --diff
7 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type PYTHON_FILES="deepagents_harbor/ tests/"
[ "deepagents_harbor/ tests/" = "" ] || uv run --group test ty check deepagents_harbor/ tests/
All checks passed!
🔍 Linting libs/partners/daytona
[ "." = "" ] || uv run --all-groups ruff check .
All checks passed!
[ "." = "" ] || uv run --all-groups ruff format . --diff
8 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type
uv run --all-groups ty check langchain_daytona
All checks passed!
🔍 Linting libs/partners/modal
[ "." = "" ] || uv run --all-groups ruff check .
All checks passed!
[ "." = "" ] || uv run --all-groups ruff format . --diff
8 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type
uv run --all-groups ty check langchain_modal
All checks passed!
🔍 Linting libs/partners/runloop
[ "." = "" ] || uv run --all-groups ruff check .
All checks passed!
[ "." = "" ] || uv run --all-groups ruff format . --diff
8 files already formatted
/Library/Developer/CommandLineTools/usr/bin/make type
uv run --all-groups ty check langchain_runloop
All checks passed!
✅ All packages linted!
``` | 2 个月前 |