feat: Design architecting-act skill for LangGraph projects - #4
Merged
qjrm1430 merged 3 commits intoNov 15, 2025
Merged
Conversation
…esign Add comprehensive skill for designing LangGraph architectures through interactive 4-stage process. This skill guides users through architectural decisions before implementation, generating formalized CLAUDE.md documents. Features: - 4-stage interactive workflow (Understand → Constraints → Design → Finalize) - 6 decision framework resources (patterns, state, nodes, edges, subgraphs, anti-patterns) - Automated architecture validation script (anti-pattern detection) - CLAUDE.md generation script (interactive & CLI modes) - Template-based documentation generation - LangGraph 1.0 focused (verified against official docs) - SOLID principles for node architecture - No code in resources (conceptual/decision frameworks only) Components: - SKILL.md: Main interactive guide (404 lines, ~3.2k tokens) - Resources: Decision frameworks (~17k tokens total) * workflow-patterns.md: Pattern selection (ReAct, Plan-Execute, etc.) * state-design-guide.md: State schema design with reducers * node-architecture-guide.md: SOLID node decomposition * edge-routing-guide.md: Conditional routing strategies * subgraph-decisions.md: When/how to use subgraphs * anti-patterns.md: Common mistakes and fixes - Scripts: * generate_claude_md.py: Interactive CLAUDE.md generator * validate_architecture.py: Architecture validation tool - Templates: * CLAUDE.md.template: Architecture document template Token efficiency: - Frequently accessed resources <2k tokens (patterns, anti-patterns) - All resources <4k tokens (under primary constraint) - Total skill ~18.5k tokens Integration: - First skill in 4-skill Act Operator skillset - Outputs CLAUDE.md for developing-cast skill handoff - Validates against LangGraph 1.0 best practices Also update .gitignore to allow skills in template while excluding test projects.
Add exception to .gitignore to include skills in the scaffold template while still excluding test/sample projects ending in -act/.
Add comprehensive skill for automating Act project management through scripts and clear command guidance. Focus on maximum automation and token efficiency. Features: - 5 automation scripts (save 100-900 tokens per use) - Command cheat sheet SKILL.md (~1.1k tokens) - 3 quick reference resources (~3.6k tokens total) - Total skill: ~7k tokens (highly optimized) - All scripts tested and working Scripts: - create_cast.py: Create cast with full boilerplate (~300 tokens saved) * Extends `act cast -c` with complete module structure * Adds state.py, models.py, agents.py, tools.py, prompts.py * Proper imports, type hints, and docstrings - project_info.py: Display project status (~150 tokens saved) * Shows Python version, packages, casts, dependencies * Single command vs multiple queries - validate_project.py: Check structure and config (~200 tokens saved) * Validates files, directories, pyproject.toml * Checks cast structures and workspace config * --fix flag for automatic repairs - batch_dependencies.py: Batch add/remove packages (~100 tokens saved) * Add/remove multiple packages in one command * Dev dependency support - sync_check.py: Sync with change tracking (~100 tokens saved) * Shows added/removed packages after sync * --all-extras for dev/test/lint groups Resources: - uv-commands.md: Essential uv command reference (~825 tokens) * Dependency management, environment sync, tools * Common workflows and best practices - cast-structure.md: Cast directory layout (~1.4k tokens) * Standard structure, file purposes, import patterns * Minimal vs full boilerplate options - troubleshooting.md: Common issues and fixes (~1.4k tokens) * Environment, dependency, cast, LangGraph issues * Symptom → Fix → Explanation format Design Philosophy: - Scripts do the work, not Claude - SKILL.md is command index, not tutorial - Resources are quick lookup, not manuals - Minimum 100-token savings per script - Maximum automation for developer productivity Token Efficiency: - SKILL.md: ~1,146 tokens (<2k target, <5k limit) - Resources: <2k tokens each - Total context: ~7k tokens (highly optimized) - ROI: Skill pays for itself after ~6 operations Integration: - Skill 2 of 4 in Act Operator skillset - Bridges architecting-act (CLAUDE.md) → developing-cast - Handles all project setup and environment management
qjrm1430
deleted the
claude/architecting-act-skill-011UJzXp5fV574z5CmHiJ8YP
branch
December 5, 2025 06:12
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
✅ Review Readiness Checklist (Required before review)
Complete all items below before marking your PR ready for review. After completion, delete these instructions and replace with your actual PR message.
PR title format:
{TYPE}({SCOPE}): {DESCRIPTION}feat(cli): add cast scaffolding optionfix(scaffold): resolve snake_case normalization bugdocs(readme): clarify Python 3.12+ requirement{TYPE}values:feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert,release{SCOPE}values (optional): project areacli,scaffold,utils,docs,tests,workflow,cookiecutterPR message: Replace this entire checklist with the template below
Fixes #123)Add tests and docs: If you add a new feature/integration, include
README.mdor scaffold template docs (e.g.,act_operator/act_operator/scaffold/{{ cookiecutter.project_dir }}/README.md)Lint and test: From the root of modified package(s), run and ensure all pass
uv run ruff check . uv run pytest -qWe will not consider a PR unless these two pass in CI. See
CONTRIBUTING.mdfor more.Additional guidelines
pyproject.toml(even optional) unless required for runtime/tests.📝 Summary
📄 Description
🔗 Issue / Dependencies / Mentions
✅ Local Checks
uv run ruff check .passeduv run pytest -qpassed💡 Notes (Optional)
🔗 Related Issue(s)