using-craft
Skill0 starsChanged 56 days agoMITView on GitHub
Lifecycle router for Craft: pick exactly one phase-appropriate skill from upstream packs (Addy agent-skills, optional Superpowers). Read before non-trivial work. Use when starting features, unsure which skill applies, onboarding Craft, or adding Craft-native skills. Never copy upstream skill bodies into Craft.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- craft-adoptSkill
- craft-promoteSkill
- engineering-ledgerSkill
- product-managementSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 121
Only for patterns you distilled (not forks of Addy):
- Very specific: line 125
Create skills/<kebab-name>/SKILL.md with triggers, workflow, verification, anti-patterns
- Very specific: line 126
Update README.md and craft.manifest.yaml craft_native list
- Very specific: line 133
Every Craft-native skill must define:
- Very specific: line 152
All skills and ledger templates will reside self-contained inside .agents/skills/ and docs/engineering-ledger/ in that project.
- Very specific: line 165
Update upstream: npx skills update addyosmani/agent-skills — then re-run verify-deps if router behavior changed.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Using Craft
Craft is the router + memory layer. Implementation lives in upstream packs installed locally — see craft.manifest.yaml.
Full lifecycle map: docs/lifecycle-map.md
Before anything else (non-trivial work)
- Read ledger — follow
engineering-ledgerread loop (docs/engineering-ledger/INDEX.mdandphases.mdin target project). - Verify Phase Transition Threshold — confirm the current phase's exit criteria gate is satisfied before advancing to the next phase. (If in Shape, ensure
docs/northstar.mdmarket score >= 7/10). - Identify phase — Shape | Spec | Architecture | Plan | Build | Debug | Verify | Review | Ship.
- Load exactly one primary skill from table below (read full SKILL.md from disk).
- End session —
engineering-ledgerwrite loop (update DR, LL, phases, and INDEX).
When NOT to load any skill
Skip process skills for:
- Greetings, thanks, meta chat
- Single-file lookups ("where is X defined?")
- Config/env questions with a direct answer
- One-line typo fixes with zero design choice
Anti-drift rules
| Rule | Detail |
| One skill per phase | Never stack interview-me + spec-driven-development + implement |
| Gate threshold verification | Never advance active phase without meeting exit criteria in phases.md |
| Market validation gate | docs/northstar.md score must be >= 7/10 to build. If < 7, stop or pivot |
| User slash wins | /grill-me, /implement, project AGENTS.md overrides win |
| No skill hoarding | Do not read Superpowers using-superpowers "1% chance" behavior |
| Reference only | Never copy upstream SKILL.md into Craft or project repos |
| Missing skill | Run manifest install, then read — do not improvise workflow |
Resolve skill path
Search in order:
.agents/skills/<name>/SKILL.md(project-local, fromcraft-install.shin project root)~/.agents/skills/<name>/SKILL.md(user-global fallback)- Superpowers plugin cache (optional skills only)
If missing:
cd /path/to/your/project
bash /path/to/craft/scripts/craft-install.sh --profile allPhase → primary skill
| Phase | Primary skill | Pack | Optional ledger |
| Shape | product-management, interview-me, or idea-refine | Craft/Addy | Create AP-### & northstar.md |
| Spec | product-management (PRD) or spec-driven-development | Craft/Addy | DR-### for forks |
| ADR | documentation-and-adrs | Addy | Link DR ↔ ADR |
| Plan | planning-and-task-breakdown | Addy | AP ↔ tasks |
| Build | incremental-implementation | Addy | Update AP status; use for plan tickets too |
| Build (tests) | test-driven-development | Addy | Same session as build slice |
| Debug | debugging-and-error-recovery | Addy | LL-### after root cause |
| Verify | constraint-driven-development | Addy | phases.md evidence |
| Review | code-review-and-quality | Addy | INDEX session |
| Ship | shipping-and-launch | Addy | Rollback note in INDEX |
Domain overlays (replace primary for that work)
| Work | Skill |
| UI only | frontend-ui-engineering |
| Auth / input / secrets | security-and-hardening |
| Public API design | api-and-interface-design |
| Perf regression | performance-optimization |
| CI pipeline | ci-cd-and-automation |
| Project rules file | context-engineering |
| Commits / branches | git-workflow-and-versioning |
Superpowers (optional — use instead of stacking Addy)
| When | Skill |
| Greenfield creative exploration | brainstorming |
| Stuck bug, unknown layer | systematic-debugging |
| Before claiming "done" | verification-before-completion |
Craft-native skills
| Skill | When |
| engineering-ledger | Every non-trivial session (read + write) |
| product-management | PRD authoring, RICE prioritization, JTBD, telemetry |
| using-craft | Routing, adding skills, structure questions |
| craft-adopt | Bootstrap Craft into a new project |
| craft-promote | Universal LL → new Craft skill |
Adding a new Craft-native skill
Only for patterns you distilled (not forks of Addy):
- Confirm promotion-criteria.md or explicit user request
- Run
craft-promote/scripts/check-duplicate.sh <term> - Create
skills/<kebab-name>/SKILL.mdwith triggers, workflow, verification, anti-patterns - Update README.md and
craft.manifest.yamlcraft_nativelist - Commit:
feat(skills): add <name> — <one line why>
Skill quality bar
Every Craft-native skill must define:
- Triggers — when to load (and when not to)
- Workflow — numbered steps with gates
- Artifacts — files produced and where
- Verification — how to know it was followed
- Anti-patterns — agent shortcuts to reject
Initialize Craft in a Project
Like git init, initialize Craft directly in your target project repository:
cd /path/to/your/project
bash /path/to/craft/scripts/craft-install.sh --profile allAll skills and ledger templates will reside self-contained inside .agents/skills/ and docs/engineering-ledger/ in that project.
Relationship to other packs
| Pack | Craft role |
| addyosmani/agent-skills | Implementation engine — referenced, not copied |
| Superpowers | Optional debug/brainstorm/verify delegates |
| documentation-and-adrs | Irreversible forks below ledger DR layer |
| engineering-ledger | Running memory Craft owns |
Update upstream: npx skills update addyosmani/agent-skills — then re-run verify-deps if router behavior changed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.