ee0f4bd5d9
- Add comprehensive built-in commands reference (40+ commands) - Document argument handling ($ARGUMENTS, $1, $2, etc.) - Add bash execution syntax (! prefix) and file references (@ prefix) - Update frontmatter to official fields (allowed-tools, argument-hint, model, etc.) - Add Plugin Commands and MCP Slash Commands sections - Add SlashCommand Tool documentation for programmatic invocation - Add Skills vs Slash Commands comparison table - Create commit.md example with bash execution and context - Update existing examples to use official frontmatter format - Add OpenSpec proposal for change tracking
49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# Change: Update Agent Skills Lesson with Latest Documentation
|
|
|
|
## Why
|
|
|
|
The current Agent Skills lesson (03-skills) is missing several key features and best practices from the latest official Claude Code documentation at https://code.claude.com/docs/en/skills#agent-skills. Users need up-to-date information to effectively create, manage, debug, and share skills.
|
|
|
|
## What Changes
|
|
|
|
### Documentation Updates (README.md and blog-posts/03-skills.md)
|
|
|
|
1. **Enhanced Managing Skills Section** - Add comprehensive guidance for:
|
|
- Viewing available skills (via Claude and filesystem)
|
|
- Testing skills effectively
|
|
- Updating skills (with restart requirements)
|
|
- Removing skills properly
|
|
|
|
2. **Improved Debugging Section** - Add detailed troubleshooting for:
|
|
- Skills being skipped or non-functional
|
|
- Invalid YAML frontmatter detection
|
|
- Script permission issues
|
|
- Path format requirements (forward slashes)
|
|
- Multiple skills conflicting
|
|
|
|
3. **Version History Best Practice** - Add guidance on documenting skill versions in SKILL.md
|
|
|
|
4. **Enhanced allowed-tools Documentation** - Expand explanation of tool access control with:
|
|
- Use cases for read-only skills
|
|
- Security-sensitive workflow examples
|
|
- Note about permission prompts when not specified
|
|
|
|
5. **Multi-File Skill Example** - Add comprehensive example showing:
|
|
- Directory structure for complex skills
|
|
- Multiple reference files
|
|
- Scripts subdirectory
|
|
- Templates organization
|
|
|
|
6. **Plugin Skills Clarification** - Better explain how plugin-bundled skills work
|
|
|
|
### Example Updates (03-skills/ directory)
|
|
|
|
7. **Add Version History Example** - Update code-review SKILL.md to include version history section
|
|
|
|
## Impact
|
|
|
|
- Affected docs: `03-skills/README.md`, `blog-posts/03-skills.md`
|
|
- Affected examples: `03-skills/code-review/SKILL.md`
|
|
- No breaking changes - purely additive documentation improvements
|
|
- Improves user experience for skill creation and debugging
|