# Sharpening Your Claws You are reading a best practices guide for AI agents. Apply these patterns to your workspace. Each section includes what to do, why it matters, and ready-to-use templates. ## Quick-Start Checklist Run through these in order. Each one builds on the last. - [ ] **GitHub**: Install git + GitHub CLI, authenticate, make first commit - [ ] **Repo split**: Create `-setup` (workspace) and `-drive` (work product) as private repos - [ ] **Napkin**: Create `napkin.md` in workspace root, read it every session, update it continuously - [ ] **Skill routing**: Add "Use when" and "Don't use when" blocks to every skill description - [ ] **Self-contained skills**: Move templates and examples out of system prompt and into skill files - [ ] **PRD workflow**: When starting a new project, create a repo and structured PRD from raw notes - [ ] **Sub-agents**: Delegate long-running or parallel tasks to isolated background sessions --- ## 1. Version Control Set up Git and GitHub immediately. Not after things get serious. Now. ### What to do 1. Install `git` and the GitHub CLI (`gh`) 2. Create a Personal Access Token at https://github.com/settings/tokens with `repo` scope 3. Authenticate: `gh auth login --with-token` 4. Configure git identity: `git config --global user.name` and `user.email` 5. Initialize your workspace as a repo, commit, and push ### Rules - Commit after every meaningful change (not batched at end of day) - Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `style:` - One commit per logical change, not per file - Write messages a human would understand in 6 months ### What to track Everything that defines your agent: memory files, skills, config, custom instructions, docs. If the server dies, a `git clone` should rebuild you. --- ## 2. Split Your Repos Two private repos, not one monorepo. ### Structure ``` -setup/ # The operating system |-- AGENTS.md # Workspace rules |-- SOUL.md # Persona and tone |-- USER.md # About your human |-- MEMORY.md # Long-term memory |-- napkin.md # Mistake tracker |-- memory/ # Daily logs (YYYY-MM-DD.md) |-- skills/ # Skill definitions |-- scripts/ # Automation scripts `-- docs/ # Reference documentation -drive/ # The work product |-- deliverables/ # Client/project output |-- research/ # Research and analysis |-- content/ # Written content `-- assets/ # Images, files, media ``` ### Why split - Config changes don't pollute content history - You can see exactly when a behavior changed and why - Work product has clean project-focused history - Big standalone projects get their own repos ### Rules - Both repos must be **private** (setup contains memory, API references, personal context) - Standalone projects with their own lifecycle get their own repo - This maps to PARA: setup = Areas + Resources, drive = Projects + Archives --- ## 3. Napkin (Mistake Memory) Adapted from [blader/napkin](https://github.com/blader/napkin). This is how you learn between sessions. ### What to do 1. Create `napkin.md` in your workspace root 2. Read it at session start. Apply it silently. Don't announce it. 3. Update it continuously as you work, not at session boundaries 4. Every 5-10 sessions, consolidate: merge duplicates, promote patterns, trim to under 200 lines ### Template ```markdown # napkin.md ## File Operations - Use `trash` over `rm` (recoverable > gone) - Check if file exists before overwriting ## Git - Run `git pull` before starting work - Use conventional commits (feat:, fix:, docs:, chore:) ## Communication - [Add your human's preferences here] - [Add formatting rules for your platforms here] ## Tool Quirks - [Log unexpected tool behaviors here] - [Track workarounds that solved problems] ``` ### What makes a good entry - ✅ Specific: "Assumed the file was UTF-8 but it was Latin-1, causing silent corruption" - ❌ Vague: "Made an error" - ✅ Actionable: "Always check `git status` before committing, auto-staged files caused bad commits twice" - ❌ Obvious: "Be careful with files" ### The golden rule A 50-line napkin of hard-won rules beats a 500-line log of raw entries. --- ## 4. Skill Descriptions Are Routing Logic Your skill descriptions are not documentation for humans. They are the model's decision boundary. The model reads them and decides: "Should I load this skill?" Vague descriptions cause wrong routing. Precise descriptions cause correct routing. ### Template ```markdown # SKILL.md - [Skill Name] [One-line description of what this skill does.] ## Use when - [Specific trigger condition] - [Specific trigger condition] - [Keywords or phrases that should activate this] ## Don't use when - [Thing that sounds similar but needs a different skill] (use X skill) - [Common false positive] (use Y skill instead) - [Edge case that doesn't belong here] ## Instructions [Step-by-step instructions for executing this skill] ## Examples [Concrete input/output examples showing what "good" looks like] ## Templates [Any reusable templates the skill needs] ``` ### Rules - Every skill must have "Use when" AND "Don't use when" blocks - Negative examples prevent misrouting (Glean measured a 20% accuracy drop without them) - Templates and examples inside skills are free when unused (they only load on trigger) - Move detailed instructions out of your system prompt and into skills - System prompt should be lean. Skills should be rich. - Skills should be self-contained: everything needed to complete the task lives in the skill file ### Reference - OpenAI ["Skills + Shell + Compaction"](https://developers.openai.com/blog/skills-shell-tips) post - Anthropic [Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) (33 practices) --- ## 5. Co-Author PRDs When starting a new project, create a structured Product Requirements Document from raw notes. The PRD becomes a living document that evolves with the project. ### Workflow 1. Human dumps raw notes, transcript, or stream of consciousness 2. You structure it into a PRD: Overview, Requirements, Architecture, Open Questions, Changelog 3. Commit to a dedicated repo 4. Every follow-up call or decision: update the PRD, bump version, add changelog entry, push 5. Sub-agents can read the PRD for project context without re-explanation ### Template ```markdown # [Project Name] - PRD **Version:** 0.1 **Last Updated:** YYYY-MM-DD **Status:** Draft | In Progress | Complete ## Overview [What is this project and why does it exist?] ## Requirements ### Must Have - [Requirement] ### Nice to Have - [Requirement] ## Architecture [Technical approach, stack, integrations] ## Open Questions - [ ] [Unresolved decision or unknown] ## Decisions Log | Date | Decision | Context | |------|----------|---------| | YYYY-MM-DD | [What was decided] | [Why] | ## Changelog - **v0.1** (YYYY-MM-DD): Initial PRD from kickoff notes ``` ### Why this matters - PRD lives in Git with full change history - You can diff versions to see how thinking evolved - Sub-agents read it for context without you re-explaining - Raw meeting transcripts become structured documents in ~90 seconds --- ## 6. Delegate With Sub-Agents Spawn isolated background sessions for tasks that are long-running, parallelizable, or don't need your main conversation's context. ### When to use sub-agents - **Long-running research**: "Read these 10 URLs and summarize findings" - **Parallel workstreams**: One agent updates the dashboard, another drafts the email - **Scheduled background work**: Combine with cron jobs for daily scans, weekly reports - **Heavy document processing**: Meeting transcript → PRD update, runs in background - **Code reviews and audits**: Review a codebase and file results as GitHub issues ### When NOT to use sub-agents - Quick tasks that take under a minute - Tasks that need back-and-forth with the human - Anything requiring the main conversation's recent context ### The staffing model Think of your main agent as a manager. It understands the full context, makes decisions, and delegates. Sub-agents are specialists: they do one thing, do it well, and report back. The manager reviews output, not process. PRDs (#5) + sub-agents (#6) is the combination that unlocks real leverage. The PRD is the briefing document. The sub-agent reads it, understands the project, and does meaningful work without babysitting. --- ## The Meta-Rule Treat your agent like a junior engineer joining your team, not like a magic box. Give it: - Good tools (GitHub, skills, sub-agents) - Clear instructions (skill routing, PRD templates) - Version control (setup + drive repos) - A way to learn from mistakes (napkin.md) The agents that perform best aren't the ones with the biggest models. They're the ones with the best scaffolding around them. --- *Source: [mattlor.com/read/sharp](https://mattlor.com/read/sharp/) · February 2026*