chore: Archive update-skills-lesson change
This commit is contained in:
Luong NGUYEN
@@ -0,0 +1,48 @@
|
||||
# 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
|
||||
@@ -0,0 +1,64 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Managing Skills Documentation
|
||||
The skills lesson SHALL provide comprehensive guidance for managing skills including viewing available skills, testing skills, updating skills with restart requirements, and removing skills.
|
||||
|
||||
#### Scenario: User wants to view available skills
|
||||
- **WHEN** a user wants to see what skills are available
|
||||
- **THEN** the documentation provides both CLI method (asking Claude "What Skills are available?") and filesystem method (ls ~/.claude/skills/ and ls .claude/skills/)
|
||||
|
||||
#### Scenario: User wants to test a skill
|
||||
- **WHEN** a user wants to test if their skill works
|
||||
- **THEN** the documentation explains that skills activate automatically based on matching descriptions, with example test queries
|
||||
|
||||
#### Scenario: User wants to update a skill
|
||||
- **WHEN** a user modifies a SKILL.md file
|
||||
- **THEN** the documentation explains that changes take effect on next Claude Code startup and restart is required if already running
|
||||
|
||||
#### Scenario: User wants to remove a skill
|
||||
- **WHEN** a user wants to remove a skill
|
||||
- **THEN** the documentation provides rm -rf commands for both personal and project skills, with git commit for project skills
|
||||
|
||||
### Requirement: Enhanced Debugging Guidance
|
||||
The skills lesson SHALL provide detailed debugging guidance for common skill issues including skipped skills, YAML errors, script permissions, and path formats.
|
||||
|
||||
#### Scenario: Skill not being discovered
|
||||
- **WHEN** Claude doesn't use a user's skill
|
||||
- **THEN** the documentation explains to check: description specificity, YAML syntax validity (opening/closing ---, no tabs), and correct file path location
|
||||
|
||||
#### Scenario: Skill has errors
|
||||
- **WHEN** a skill has runtime errors
|
||||
- **THEN** the documentation explains to check: dependency installation, script execute permissions (chmod +x), and forward slash usage in paths
|
||||
|
||||
#### Scenario: Multiple skills conflict
|
||||
- **WHEN** multiple skills are activated unexpectedly
|
||||
- **THEN** the documentation explains using distinct trigger terms in descriptions to help Claude choose the right skill
|
||||
|
||||
### Requirement: Version History Documentation
|
||||
The skills lesson SHALL include a best practice example for documenting skill version history in SKILL.md files.
|
||||
|
||||
#### Scenario: User wants to track skill versions
|
||||
- **WHEN** a user maintains a skill over time
|
||||
- **THEN** the documentation provides a version history markdown template with date and description format
|
||||
|
||||
### Requirement: Enhanced Tool Access Control Documentation
|
||||
The skills lesson SHALL provide expanded documentation for the allowed-tools feature including use cases, security examples, and behavior when not specified.
|
||||
|
||||
#### Scenario: User wants a read-only skill
|
||||
- **WHEN** a user wants to create a skill that cannot modify files
|
||||
- **THEN** the documentation provides an example with allowed-tools: Read, Grep, Glob
|
||||
|
||||
#### Scenario: User wants security-sensitive workflow
|
||||
- **WHEN** a user has a security-sensitive skill
|
||||
- **THEN** the documentation explains how allowed-tools restricts Claude's capabilities within that skill context
|
||||
|
||||
#### Scenario: allowed-tools not specified
|
||||
- **WHEN** a user doesn't specify allowed-tools
|
||||
- **THEN** the documentation explains that Claude will ask for permission as normal
|
||||
|
||||
### Requirement: Multi-File Skill Example
|
||||
The skills lesson SHALL include a comprehensive example of a multi-file skill showing directory structure with multiple reference files, scripts, and templates.
|
||||
|
||||
#### Scenario: User wants to create complex skill
|
||||
- **WHEN** a user needs a skill with supporting files
|
||||
- **THEN** the documentation provides a complete directory structure example showing SKILL.md, reference files (FORMS.md, REFERENCE.md), scripts subdirectory, and progressive disclosure explanation
|
||||
@@ -0,0 +1,27 @@
|
||||
# Tasks: Update Agent Skills Lesson
|
||||
|
||||
## 1. Update Main README (03-skills/README.md)
|
||||
|
||||
- [x] 1.1 Add "Managing Skills" section with viewing, testing, updating, removing guidance
|
||||
- [x] 1.2 Expand "Troubleshooting Guide" with debugging tips for skipped skills, YAML errors, script permissions, path formats
|
||||
- [x] 1.3 Add "Version History Best Practice" section with example
|
||||
- [x] 1.4 Enhance "allowed-tools" documentation with use cases and security examples
|
||||
- [x] 1.5 Add "Multi-File Skill Example" showing complex skill structure with multiple reference files
|
||||
|
||||
## 2. Update Blog Post (blog-posts/03-skills.md)
|
||||
|
||||
- [x] 2.1 Add "Managing Skills" section mirroring README updates
|
||||
- [x] 2.2 Expand troubleshooting with debugging guidance from official docs
|
||||
- [x] 2.3 Add version history best practice
|
||||
- [x] 2.4 Enhance allowed-tools explanation
|
||||
- [x] 2.5 Add multi-file skill example
|
||||
|
||||
## 3. Update Example Skills
|
||||
|
||||
- [x] 3.1 Add version history section to `03-skills/code-review/SKILL.md`
|
||||
|
||||
## 4. Validation
|
||||
|
||||
- [x] 4.1 Verify all code examples are syntactically correct
|
||||
- [x] 4.2 Ensure consistency between README and blog post
|
||||
- [x] 4.3 Test that existing examples still work with updated documentation
|
||||
Reference in New Issue
Block a user