aws / aws/agent-toolkit-for-aws

Skill descriptions consume too much context budget per session

Open
#54 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
2.7k
Forks
314
Avg merge
1d 1h
Merged PRs (30d)
51

Description

Installing the plugin adds 13 aws-core:* skills to the listing that is injected into every session's context. Even without invoking any skill, the description text for these skills costs ~1,600 tokens per session — roughly 73% of Claude Code's default 1% skill listing budget.

This causes the harness to emit a truncation warning and drop skill descriptions silently:

Skill listing will be truncated
11 descriptions dropped (full descriptions kept for most-used skills)
run /skills to disable some, or raise skillListingBudgetFraction in settings.json

Measured description sizes (chars/4 approximation):

Skill ~Tokens
aws-core:aws-observability 219
aws-core:aws-serverless 210
aws-core:aws-amplify 208
aws-core:amazon-bedrock 193
aws-core:aws-containers 155
aws-core:aws-sdk-python-usage 133
aws-core:aws-billing-and-cost-management 123
aws-core:aws-cdk 104
aws-core:aws-messaging-and-streaming 78
aws-core:aws-sdk-js-v3-usage 69
aws-core:aws-cloudformation 68
aws-core:aws-sdk-swift-usage 29
aws-core:aws-iam 17
Total 1,606

The descriptions are long because they double as trigger conditions ("ALSO USE for...", "Use this skill whenever..."), which is understandable — but it means installing this plugin has a persistent per-session cost even when doing nothing AWS-related.

Possible mitigations (in order of preference):

  1. Trim descriptions — separate the trigger heuristics from the user-facing description; only the short description needs to be in the listing
  2. Opt-in skills — let users enable only the aws-core:* skills they actually use, rather than registering all 13 on install
  3. Lazy listing — only surface skills in the listing when the working directory contains AWS-related files (e.g., amplify/, cdk.json, template.yaml, *.tf)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Install the plugin and reproduce the skill-listing truncation warning, then inspect how the 13 aws-core skills and their descriptions are registered. Compare the proposed trimming, opt-in, and lazy-listing approaches with maintainers; done means AWS skill descriptions no longer consume excessive per-session context or trigger silent truncation.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
ai-infra-agents, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.