Skillify

Capture what this session learned as a skill the next session can run without the conversation. Use the host's native authoring tools for package mechanics; this skill owns workflow extraction, personal conventions, and the catalog package rules. lesson-learned decides whether a lesson belongs in a skill at all.

Workflow

1. Extract from the session: the goal, the user's trigger phrases, the exact commands that worked (with flags), the user's corrections, the decisions and why, the dead ends, and the tools required; drop session-specific paths, one-off values, and secrets.
2. Apply the admission rule in package rules before choosing an owner or scope.
3. Check the catalog: list names with descriptions via rg -m1 '^description:' ~/.agents/skills/*/SKILL.md .agents/skills/*/SKILL.md (preview gh skill list also scans every host directory, without descriptions), then read any neighbor with an overlapping description; extend it when the workflow is the same, write a new skill only for a distinct trigger, and link neighbors instead of copying them.
4. Choose the scope:
   • Global (reusable, tool-generic): ~/.agents/skills/<name>/, the skills/ directory of the dot repository, whose dot-skills skill owns registration (link declaration) and mise run check:skills. Installation or tooling changes also need their affected tests.
   • Local (repository-specific commands, data, or conventions): .agents/skills/<name>/ in the project, which agy reads natively; add the .claude/skills -> ../.agents/skills link only when the repository is also used with Claude Code, per agent-project. In the dot repository, local skills also register through dot-skills.
5. Write from the template: copy skill.md and apply the size and output-efficiency rules in package rules; long configs and examples go to references/.
6. Validate: frontmatter name equals the directory, every link resolves, every resource is reachable from its owner, and mise run check:skills passes for a global skill. In another repository, the preview gh skill publish --dry-run .agents/skills checks the Agent Skills specification without publishing and exits 1 on errors.
7. Test behavior: follow the adoption check for substantial additions or routing changes: a natural trigger, a neighboring task, and an observable outcome in an isolated fixture. Keep paid or external effects within scope and report unavailable host validation separately.
8. Report: the path, the description, and the scope.

Extracting from AGENTS.md

Keep durable preferences in the global persona and repository invariants in project AGENTS.md. Move procedures into the existing owning skill where possible; create a global or local skill only for a distinct reusable workflow. Leave a routing cue and re-run repository-docs.

Gotchas

• Descriptions route, bodies instruct: the description decides when the skill loads; the body decides what happens. Do not summarize the workflow in the description.
• Keep dates current: set created and updated to today; bump updated on every later edit.
• Follow vendor policy for third-party content: when the workflow came from an external skill, follow the shared vendor-skill policy instead of retyping it.
• Promote or publish per portability: promoting a guide to a package or publishing one standalone follows portability.

Documentation

• Agent Skills specification
• Catalog and usage review: measure discovery cost and bounded activation evidence before adding or retiring global entries.