john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reduce context token usage by 79% — fix silent component exclusion (#161)

Browse Source 
* Update create-agent-skills to match 2026 official docs, add /triage-prs command

- Rewrite SKILL.md to document that commands and skills are now merged
- Add new frontmatter fields: disable-model-invocation, user-invocable, context, agent
- Add invocation control table and dynamic context injection docs
- Fix skill-structure.md: was incorrectly recommending XML tags over markdown headings
- Update official-spec.md with complete 2026 specification
- Add local /triage-prs command for PR triage workflow
- Add PR triage plan document

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* [2.31.0] Reduce context token usage by 79%, include recent community contributions

The plugin was consuming 316% of Claude Code's description character budget
(~50,500 chars vs 16,000 limit), causing components to be silently excluded.
Now at 65% (~10,400 chars) with all components visible.

Changes:
- Trim all 29 agent descriptions (move examples to body)
- Add disable-model-invocation to 18 manual commands
- Add disable-model-invocation to 6 manual skills
- Include recent community contributions in changelog
- Fix component counts (29 agents, 24 commands, 18 skills)

Contributors: @trevin, @terryli, @robertomello, @zacwilliams,
@aarnikoskela, @samxie, @davidalley

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix: keep disable-model-invocation off commands called by /lfg, rename xcode-test

- Remove disable-model-invocation from test-browser, feature-video,
  resolve_todo_parallel — these are called programmatically by /lfg and /slfg
- Rename xcode-test to test-xcode to match test-browser naming convention

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix: keep git-worktree skill auto-invocable (used by /workflows:work)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(converter): support disable-model-invocation frontmatter

Parse disable-model-invocation from command and skill frontmatter.
Commands/skills with this flag are excluded from OpenCode command maps
and Codex prompt/skill generation, matching Claude Code behavior where
these components are user-only invocable.

Bump converter version to 0.3.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
2026-02-08 22:28:51 -06:00
committed by GitHub
parent 04ee7e4506
commit f744b797ef
71 changed files with 1765 additions and 767 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md
View File

@@ -1,36 +1,56 @@
# Anthropic Official Skill Specification
# Official Skill Specification (2026)
Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
## Commands and Skills Are Merged
Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
If a skill and a command share the same name, the skill takes precedence.
## SKILL.md File Structure
Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
### Basic Format
Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
```markdown
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
description: What it does and when to use it
---
# Your Skill Name
## Instructions
Provide clear, step-by-step guidance for Claude.
Clear, step-by-step guidance.
## Examples
Show concrete examples of using this Skill.
Concrete examples of using this skill.
```
## Required Frontmatter Fields
## Complete Frontmatter Reference
All fields are optional. Only `description` is recommended.
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. Default: `false` |
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` |
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
| `model` | No | Model to use: `haiku`, `sonnet`, or `opus` |
| `context` | No | Set `fork` to run in isolated subagent context |
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name |
| `hooks` | No | Hooks scoped to this skill's lifecycle |
## Invocation Control
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|-------------|----------------|-------------------|--------------------------|
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
## Skill Locations & Priority
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
| Type | Path | Applies to |
|------|------|-----------|
| **Enterprise** | See managed settings | All users in organization |
| **Personal** | `~/.claude/skills/` | You, across all projects |
| **Project** | `.claude/skills/` | Anyone working in repository |
| **Plugin** | Bundled with plugins | Anyone with plugin installed |
| Enterprise | See managed settings | All users in organization |
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
| Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
## How Skills Work
1. **Discovery**: Claude loads only name and description at startup
2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
3. **Execution**: Claude follows the Skill's instructions and loads referenced files
1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
2. **Activation**: When your request matches a skill's description, Claude loads the full content
3. **Execution**: Claude follows the skill's instructions
**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
## String Substitutions
## Progressive Disclosure Pattern
| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed when invoking |
| `$ARGUMENTS[N]` | Specific argument by 0-based index |
| `$N` | Shorthand for `$ARGUMENTS[N]` |
| `${CLAUDE_SESSION_ID}` | Current session ID |
Keep `SKILL.md` under 500 lines by linking to supporting files:
## Dynamic Context Injection
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
```markdown
## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`
```
Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
## Progressive Disclosure
```
my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
├── SKILL.md # Entry point (required)
├── reference.md # Detailed docs (loaded when needed)
├── examples.md # Usage examples (loaded when needed)
└── scripts/
└── helper.py (utility script - executed, not loaded)
└── helper.py # Utility script (executed, not loaded)
```
### Example SKILL.md with References
Keep SKILL.md under 500 lines. Link to supporting files:
```markdown
---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
allowed-tools: Read, Bash(python:*)
---
# PDF Processing
## Quick start
Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
For API details, see [reference.md](reference.md).
```
For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
## Running in a Subagent
## Requirements
Packages must be installed:
```bash
pip install pypdf pdfplumber
```
```
## Restricting Tool Access
Add `context: fork` to run in isolation:
```yaml
---
name: reading-files-safely
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---
```
Benefits:
- Read-only Skills that shouldn't modify files
- Limited scope for specific tasks
- Security-sensitive workflows
## Writing Effective Descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
**Always write in third person.** The description is injected into the system prompt.
- **Good:** "Processes Excel files and generates reports"
- **Avoid:** "I can help you process Excel files"
- **Avoid:** "You can use this to process Excel files"
**Be specific and include key terms:**
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Avoid vague descriptions:**
```yaml
description: Helps with documents # Too vague!
```
## Complete Example: Commit Message Generator
```markdown
---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
# Generating Commit Messages
## Instructions
1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
- Summary under 50 characters
- Detailed description
- Affected components
## Best practices
- Use present tense
- Explain what and why, not how
Research $ARGUMENTS thoroughly...
```
## Complete Example: Code Explanation Skill
```markdown
---
name: explaining-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
# Explaining Code
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.
```
The skill content becomes the subagent's prompt. It won't have access to conversation history.
## Distribution
- **Project Skills**: Commit `.claude/skills/` to version control
- **Plugins**: Add `skills/` directory to plugin with Skill folders
- **Project skills**: Commit `.claude/skills/` to version control
- **Plugins**: Add `skills/` directory to plugin
- **Enterprise**: Deploy organization-wide through managed settings