Skip to content

feat: Add build workflow skill for Titan CLI plugins#190

Open
r-pedraza wants to merge 4 commits intomasterfrom
feat/titan-build-workflow-skill
Open

feat: Add build workflow skill for Titan CLI plugins#190
r-pedraza wants to merge 4 commits intomasterfrom
feat/titan-build-workflow-skill

Conversation

@r-pedraza
Copy link
Copy Markdown
Contributor

# Pull Request

## 📝 Summary
<!-- Brief description of what this PR does (2-3 sentences) -->
This PR introduces a new "skill" for the Titan AI builder, which is a comprehensive guide on architectural best practices and common anti-patterns for developing Titan CLI plugins. The document serves as a knowledge base to help the AI generate more consistent, maintainable, and architecturally compliant code. This aims to improve the quality of generated plugins and reduce the need for manual corrections during code review.

## 🔧 Changes Made
<!-- Bullet list of key changes -->
- Added a new skill file: `.titan/skills/titan-builder/COMMON_MISTAKES.md`.
- This document details 11 common mistakes found in plugin development, providing "wrong" vs. "correct" code examples.
- Includes a quick reference table summarizing the expected return types for each architectural layer (Client, Service, Operations, Mappers, etc.) to enforce separation of concerns.
- Provides detailed explanations on why these patterns are important, focusing on concepts like public vs. internal APIs, business logic placement, and type safety.

## 🧪 Testing
<!-- How has this been tested? Check all that apply -->
- [ ] Unit tests added/updated (`poetry run pytest`)
- [ ] All tests passing (`make test`)
- [ ] Manual testing with `titan-dev`

<!-- If unit tests were added, briefly describe what is covered -->
This is a documentation-only change and does not contain executable code. The content has been manually reviewed for clarity and technical accuracy.

## 📊 Logs
<!-- List new log events introduced by this PR, or check the box if none -->
- [x] No new log events

<!-- If logs were added, list them:
- `event_name` (DEBUG/INFO/ERROR) — description of when it fires and what fields it includes
Example:
- `git_command_ok` (DEBUG) — subcommand, duration
- `ai_call_failed` (DEBUG) — provider, operation, max_tokens, duration
-->

## ✅ Checklist
- [ ] Self-review done
- [ ] Follows the project's [logging rules](.claude/docs/logging.md) (no secrets, no content in logs)
- [ ] New and existing tests pass
- [ ] Documentation updated if needed

@r-pedraza r-pedraza self-assigned this Mar 30, 2026
r-pedraza and others added 3 commits March 31, 2026 15:46
Breaking down the 5,446-line single skill into focused, specialized skills
following Anthropic's Progressive Disclosure principle.

Skills created:
- titan-workflows (885 lines): YAML workflows, hooks, extends
- titan-plugin-architecture (655 lines): 5-layer overview
- titan-layer-details (841 lines): Deep dive per layer
- titan-operations (936 lines): Business logic pattern
- titan-testing (1,127 lines): Unit tests, coverage
- titan-ui-steps (1,072 lines): Textual TUI, ctx.textual API
- titan-antipatterns (1,478 lines): Common mistakes

Benefits:
- 81% less context loaded on average (999 vs 5,446 lines)
- Each skill independently invocable
- Better maintainability and composability
- Follows Anthropic's skill design best practices

Total: 6,994 lines across 7 skills (avg 999 lines/skill)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Following "The Complete Guide to Building Skills for Claude", applied 3
improvements to all 7 specialized skills:

1. Enhanced descriptions with specific trigger phrases
   - Users can now invoke skills with natural language
   - Examples: "create workflow", "common mistakes", "test this"

2. Added metadata (author, version)
   - Follows Anthropic's frontmatter recommendations
   - Consistent versioning across all skills

3. Added Quick Examples and Troubleshooting sections
   - 3 real-world scenarios per skill
   - Common issues with solutions
   - Improves discoverability and usability

Changes per skill:
- titan-workflows: +60 lines (examples + troubleshooting)
- titan-plugin-architecture: +75 lines
- titan-operations: +55 lines
- titan-testing: +60 lines
- titan-ui-steps: +65 lines
- titan-antipatterns: +60 lines
- titan-layer-details: +70 lines

Total: +445 lines of practical guidance

Benefits:
- Better skill triggering with natural phrases
- Real-world examples help users understand usage
- Troubleshooting reduces support burden
- Follows Anthropic's Progressive Disclosure principle

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Created a comprehensive meta-skill that teaches Claude how to create new
skills following Anthropic's best practices from "The Complete Guide to
Building Skills for Claude".

Features:
- Complete skill creation process (step-by-step)
- YAML frontmatter best practices
- Progressive Disclosure (3-level system) explained
- Trigger phrase patterns and examples
- Validation checklist (before finalizing)
- Common patterns (tool wrapper, workflow, knowledge)
- Real-world examples of skill creation
- Troubleshooting common issues

The skill includes:
- Core Anthropic principles (composability, portability)
- Required and optional frontmatter fields
- Instructions structure recommendations
- 3 Quick Examples showing usage
- 3 Troubleshooting scenarios
- DO/DON'T best practices summary

Use when: User says "create a skill", "new skill", "build a skill", or
asks about "skill structure", "skill best practices".

This ensures all future skills follow the same high-quality standards
we established in this PR.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant