Artifact-Type-Tailored Context Skill

Purpose

Compress individual artifacts within a specified token budget using tiered summarization strategies. This skill operates in isolated forked context to prevent polluting the parent agent's context with large raw artifacts.

Task Context

You are responsible for compressing a single artifact file to fit within a token budget. Your responsibilities:

Read the raw artifact from the specified path
Count its tokens using the count_tokens.py script
Apply appropriate tiered summarization strategy
Return structured JSON with metadata

Success criteria:

Compressed content fits within token budget (or is properly truncated)
Valid JSON response with all required fields
Metadata accurately reflects truncation status

Input Parameters

You receive three required parameters:

Parameter	Type	Description
`artifact_path`	string	Path to artifact file relative to `$CLOSEDLOOP_WORKDIR`
`task_description`	string	Compression guidance (e.g., "preserve function signatures")
`token_budget`	integer	Maximum allowed tokens for compressed output

Execution Workflow

Step 1: Read Artifact

Read the artifact from its absolute path:

# Construct full path
ARTIFACT_FULL_PATH="$CLOSEDLOOP_WORKDIR/$artifact_path"

Use the Read tool to load the artifact content. If the file does not exist, skip to error handling.

Step 2: Count Raw Tokens

Invoke the count_tokens.py script to get accurate token count:

cd "$CLOSEDLOOP_WORKDIR" && uv run count_tokens.py "$artifact_path"

Expected output format:

{
  "input_tokens": 1234
}

Parse the JSON output and extract input_tokens as raw_tokens.

Error handling:

If count_tokens.py fails (exit code non-zero), fallback to character-based heuristic: raw_tokens = len(content) / 4
Add warning to content preamble: [WARNING: Token count estimated via heuristic due to count_tokens.py failure]\n\n

Step 3: Apply Tiered Summarization Strategy

Choose strategy based on raw token count relative to budget:

Tier 1: Full Content (raw_tokens <= budget)

Condition: raw_tokens <= token_budget

Action: Return artifact unchanged

Metadata:

compacted_tokens = raw_tokens
truncated = false

No further processing needed.

Tier 2: Intelligent Compression (budget < raw_tokens <= budget * 1.5)

Condition: token_budget < raw_tokens <= token_budget * 1.5

Action: Apply artifact-type-specific compression preserving structure

Compression strategies by artifact type:

Artifact Type	Strategy
Code diffs	Keep function signatures, class declarations, and error messages. Summarize method bodies with `// ... (implementation omitted for brevity)`. Remove comments and blank lines.
JSON files	Keep all keys and structure. For arrays longer than 10 items, keep first 5 and last 2, replace middle with `{"_truncated": "N items omitted"}`. Truncate string values over 200 chars.
Log files	Keep all ERROR and WARNING lines. Summarize consecutive INFO lines with `... (N info lines omitted)`. Keep first and last 10 lines intact.
Plan/PRD markdown	Keep all headings, tables, and code blocks. Summarize paragraph text preserving key nouns and action verbs. Remove redundant examples.

Validation:

After compression, count tokens again:

cd "$CLOSEDLOOP_WORKDIR" && uv run count_tokens.py <(echo "$compressed_content")

Decision tree:

If compacted_tokens <= token_budget: Success → Return with truncated = false
If compacted_tokens > token_budget: Compression failed → Fallback to Tier 3

Tier 3: Hard Truncation (raw_tokens > budget * 1.5 OR Tier 2 failed)

Condition: raw_tokens > token_budget * 1.5 OR compression in Tier 2 exceeded budget

Action: Hard truncate at character boundary

Algorithm:

Estimate truncation point: char_limit = token_budget * 4 (heuristic: 4 chars per token)
Find last paragraph boundary (double newline \n\n) before char_limit
Truncate at that boundary
Calculate truncated token count: truncated_tokens = raw_tokens - token_budget
Append truncation marker:

[TRUNCATED: content exceeds budget, remaining {truncated_tokens} tokens omitted]

Metadata:

compacted_tokens = token_budget (approximate)
truncated = true

Step 4: Return JSON Response

Return structured JSON with strict schema:

{
  "artifact_name": "path/to/artifact.ext",
  "raw_tokens": 5000,
  "compacted_tokens": 2000,
  "truncated": false,
  "content": "compressed artifact content here..."
}

Field descriptions:

Field	Type	Description
`artifact_name`	string	Original artifact_path parameter
`raw_tokens`	integer	Token count from count_tokens.py on raw artifact
`compacted_tokens`	integer	Token count after compression (from count_tokens.py validation or estimate for Tier 1/3)
`truncated`	boolean	`true` if Tier 3 truncation applied, `false` otherwise
`content`	string	Compressed or truncated artifact content

Error Handling

Artifact Not Found

Condition: artifact_path does not exist at $CLOSEDLOOP_WORKDIR/<artifact_path>

Response:

{
  "artifact_name": "path/to/missing.ext",
  "raw_tokens": 0,
  "compacted_tokens": 0,
  "truncated": true,
  "content": "[ERROR: artifact not found at $CLOSEDLOOP_WORKDIR/path/to/missing.ext]"
}

count_tokens.py Failure

Condition: Script exits with non-zero code or returns invalid JSON

Action:

Fallback to character-based heuristic: raw_tokens = len(content) / 4
Prepend warning to content:

[WARNING: Token count estimated via heuristic due to count_tokens.py failure]

<original content follows>

Proceed with tiered strategy using estimated token count
Set truncated = false unless Tier 3 is applied

Invalid Compression Output

Condition: Tier 2 compression produces malformed content (e.g., invalid JSON syntax for JSON artifacts)

Action: Immediately fallback to Tier 3 hard truncation with truncated = true

Example Scenarios

Example 1: Small Artifact (Tier 1)

Input:

artifact_path: plan.json
token_budget: 5000
Raw tokens: 3200

Output:

{
  "artifact_name": "plan.json",
  "raw_tokens": 3200,
  "compacted_tokens": 3200,
  "truncated": false,
  "content": "<full plan.json content>"
}

Example 2: Medium Artifact (Tier 2)

Input:

artifact_path: git_diff
token_budget: 10000
Raw tokens: 12000 (1.2x budget)

Compression applied: Remove comments, summarize method bodies, keep signatures

Output:

{
  "artifact_name": "git_diff",
  "raw_tokens": 12000,
  "compacted_tokens": 9500,
  "truncated": false,
  "content": "<compressed diff with function signatures preserved>"
}

Example 3: Large Artifact (Tier 3)

Input:

artifact_path: outcomes.log
token_budget: 3000
Raw tokens: 25000 (8.3x budget)

Action: Hard truncate at ~12000 chars (3000 tokens * 4)

Output:

{
  "artifact_name": "outcomes.log",
  "raw_tokens": 25000,
  "compacted_tokens": 3000,
  "truncated": true,
  "content": "<first ~2900 tokens of log>\n\n[TRUNCATED: content exceeds budget, remaining 22000 tokens omitted]"
}

Notes

Context isolation: This skill runs in forked context. The raw artifact content does not pollute the parent agent's context.
Token counting accuracy: Always prefer count_tokens.py output over estimates. Only fallback to heuristics on failure.
Compression quality: Tier 2 strategies prioritize structural information (function signatures, keys) over verbose content (comments, redundant text).
Budget enforcement: Tier 3 truncation is a hard stop. Judges must lower confidence when evaluating truncated artifacts.