05c2045f06
- Move docker-compose files to .docker/compose/ - Move docker-entrypoint.sh to .docker/ - Move DOCKER.md to .docker/README.md - Move 16 implementation docs to docs/implementation/ - Delete test artifacts (block_test.txt, caddy_*.json) - Update all references in Dockerfile, Makefile, tasks, scripts - Add .github/instructions/structure.instructions.md for enforcement - Update CHANGELOG.md Root level reduced from 81 items to ~35 visible items.
192 lines
7.0 KiB
Markdown
192 lines
7.0 KiB
Markdown
# Agent Skills Migration - Research Summary
|
|
|
|
**Date**: 2025-12-20
|
|
**Status**: Research Complete - Ready for Implementation
|
|
|
|
## What Was Accomplished
|
|
|
|
### 1. Complete Script Inventory
|
|
- Identified **29 script files** in `/scripts` directory
|
|
- Analyzed all scripts referenced in `.vscode/tasks.json`
|
|
- Classified scripts by priority, complexity, and use case
|
|
|
|
### 2. AgentSkills.io Specification Research
|
|
- Thoroughly reviewed the [agentskills.io specification](https://agentskills.io/specification)
|
|
- Understood the SKILL.md format requirements:
|
|
- YAML frontmatter with required fields (name, description)
|
|
- Optional fields (license, compatibility, metadata, allowed-tools)
|
|
- Markdown body content with instructions
|
|
- Learned directory structure requirements:
|
|
- Each skill in its own directory
|
|
- SKILL.md is required
|
|
- Optional subdirectories: `scripts/`, `references/`, `assets/`
|
|
|
|
### 3. Comprehensive Migration Plan Created
|
|
|
|
**Location**: `docs/plans/current_spec.md`
|
|
|
|
The plan includes:
|
|
|
|
#### A. Directory Structure
|
|
- Complete `.agentskills/` directory layout for all 24 skills
|
|
- Proper naming conventions (lowercase, hyphens, no special characters)
|
|
- Organized by category (testing, security, utility, linting, docker)
|
|
|
|
#### B. Detailed Skill Specifications
|
|
For each of the 24 skills to be created:
|
|
- Complete SKILL.md frontmatter with all required fields
|
|
- Skill-specific metadata (original script, exit codes, parameters)
|
|
- Documentation structure with purpose, usage, examples
|
|
- Related skills cross-references
|
|
|
|
#### C. Implementation Phases
|
|
**Phase 1** (Days 1-3): Core Testing & Build
|
|
- `test-backend-coverage`
|
|
- `test-frontend-coverage`
|
|
- `integration-test-all`
|
|
|
|
**Phase 2** (Days 4-7): Security & Quality
|
|
- 8 security and integration test skills
|
|
- CrowdSec, Coraza WAF, Trivy scanning
|
|
|
|
**Phase 3** (Days 8-9): Development Tools
|
|
- Version checking, cache clearing, version bumping, DB recovery
|
|
|
|
**Phase 4** (Days 10-12): Linting & Docker
|
|
- 12 linting and Docker management skills
|
|
- Complete migration and deprecation of `/scripts`
|
|
|
|
#### D. Task Configuration Updates
|
|
- Complete `.vscode/tasks.json` with all new paths
|
|
- Preserves existing task labels and behavior
|
|
- All 44 tasks updated to reference `.agentskills` paths
|
|
|
|
#### E. .gitignore Updates
|
|
- Added `.agentskills` runtime data exclusions
|
|
- Keeps skill definitions (SKILL.md, scripts) in version control
|
|
- Excludes temporary files, logs, coverage data
|
|
|
|
## Key Decisions Made
|
|
|
|
### 1. Skills to Create (24 Total)
|
|
Organized by category:
|
|
- **Testing**: 3 skills (backend, frontend, integration)
|
|
- **Security**: 8 skills (Trivy, CrowdSec, Coraza, WAF, rate limiting)
|
|
- **Utility**: 4 skills (version check, cache clear, version bump, DB recovery)
|
|
- **Linting**: 6 skills (Go, frontend, TypeScript, Markdown, Dockerfile)
|
|
- **Docker**: 3 skills (dev env, local env, build)
|
|
|
|
### 2. Scripts NOT to Convert (11 scripts)
|
|
Internal/debug utilities that don't fit the skill model:
|
|
- `check_go_build.sh`, `create_bulk_acl_issues.sh`, `debug_db.py`, `debug_rate_limit.sh`, `gopls_collect.sh`, `cerberus_integration.sh`, `install-go-1.25.5.sh`, `qa-test-auth-certificates.sh`, `release.sh`, `repo_health_check.sh`, `verify_crowdsec_app_config.sh`
|
|
|
|
### 3. Metadata Standards
|
|
Each skill includes:
|
|
- `author: Charon Project`
|
|
- `version: "1.0"`
|
|
- `category`: testing|security|build|utility|docker|linting
|
|
- `original-script`: Reference to source file
|
|
- `exit-code-0` and `exit-code-1`: Exit code meanings
|
|
|
|
### 4. Backward Compatibility
|
|
- Original `/scripts` kept for 1 release cycle
|
|
- Clear deprecation notices added
|
|
- Parallel run period in CI
|
|
- Rollback plan documented
|
|
|
|
## Next Steps
|
|
|
|
### Immediate Actions
|
|
1. **Review the Plan**: Team reviews `docs/plans/current_spec.md`
|
|
2. **Approve Approach**: Confirm phased implementation strategy
|
|
3. **Assign Resources**: Determine who implements each phase
|
|
|
|
### Phase 1 Kickoff (When Approved)
|
|
1. Create `.agentskills/` directory
|
|
2. Implement first 3 skills (testing)
|
|
3. Update tasks.json for Phase 1
|
|
4. Test locally and in CI
|
|
5. Get team feedback before proceeding
|
|
|
|
## Files Modified/Created
|
|
|
|
### Created
|
|
- `docs/plans/current_spec.md` - Complete migration plan (replaces old spec)
|
|
- `docs/plans/bulk-apply-security-headers-plan.md.backup` - Backup of old plan
|
|
- `AGENT_SKILLS_MIGRATION_SUMMARY.md` - This summary
|
|
|
|
### Modified
|
|
- `.gitignore` - Added `.agentskills` runtime data patterns
|
|
|
|
## Validation Performed
|
|
|
|
### Script Analysis
|
|
✅ Read and understood 8 major scripts:
|
|
- `go-test-coverage.sh` - Complex coverage filtering and threshold validation
|
|
- `frontend-test-coverage.sh` - npm test with Istanbul coverage
|
|
- `integration-test.sh` - Full E2E test with health checks and routing
|
|
- `coraza_integration.sh` - WAF testing with block/monitor modes
|
|
- `crowdsec_integration.sh` - Preset management testing
|
|
- `crowdsec_decision_integration.sh` - Comprehensive ban/unban testing
|
|
- `crowdsec_startup_test.sh` - Startup integrity checks
|
|
- `db-recovery.sh` - SQLite integrity and recovery
|
|
|
|
### Specification Compliance
|
|
✅ All proposed SKILL.md structures follow agentskills.io spec:
|
|
- Valid `name` fields (1-64 chars, lowercase, hyphens only)
|
|
- Descriptive `description` fields (1-1024 chars with keywords)
|
|
- Optional fields used appropriately (license, compatibility, metadata)
|
|
- `allowed-tools` lists all external commands
|
|
- Exit codes documented
|
|
|
|
### Task Configuration
|
|
✅ Verified all 44 tasks in `.vscode/tasks.json`
|
|
✅ Mapped each script reference to new `.agentskills` path
|
|
✅ Preserved task properties (labels, groups, problem matchers)
|
|
|
|
## Estimated Timeline
|
|
|
|
- **Research & Planning**: ✅ Complete (1 day)
|
|
- **Phase 1 Implementation**: 3 days
|
|
- **Phase 2 Implementation**: 4 days
|
|
- **Phase 3 Implementation**: 2 days
|
|
- **Phase 4 Implementation**: 2 days
|
|
- **Deprecation Period**: 18+ days (1 release cycle)
|
|
- **Cleanup**: After 1 release
|
|
|
|
**Total Migration**: ~12 working days
|
|
**Full Transition**: ~30 days including deprecation period
|
|
|
|
## Risk Assessment
|
|
|
|
| Risk | Mitigation |
|
|
|------|------------|
|
|
| Breaking CI workflows | Parallel run period, fallback to `/scripts` |
|
|
| Skills not AI-discoverable | Comprehensive keyword testing, iterate on descriptions |
|
|
| Script execution differences | Extensive testing in CI and local environments |
|
|
| Documentation drift | Clear deprecation notices, redirect updates |
|
|
| Developer confusion | Quick migration timeline, clear communication |
|
|
|
|
## Questions for Team
|
|
|
|
1. **Approval**: Does the phased approach make sense?
|
|
2. **Timeline**: Is 12 days reasonable, or should we adjust?
|
|
3. **Priorities**: Should any phases be reordered?
|
|
4. **Validation**: Do we have access to `skills-ref` validation tool?
|
|
5. **Rollout**: Should we do canary releases for each phase?
|
|
|
|
## Conclusion
|
|
|
|
Research is complete with a comprehensive, actionable plan. The migration to Agent Skills will:
|
|
- Make scripts AI-discoverable
|
|
- Improve documentation and maintainability
|
|
- Follow industry-standard specification
|
|
- Maintain backward compatibility
|
|
- Enable future enhancements (skill composition, versioning, analytics)
|
|
|
|
**Plan is ready for review and implementation approval.**
|
|
|
|
---
|
|
|
|
**Next Action**: Team review of `docs/plans/current_spec.md`
|