I recently published a small repository called ai-skills. It holds three skills I use to support a job search: one that scores a job posting against my verified experience, one that tailors a resume without inventing anything, and one that researches a company before an interview.
The domain is personal, but the design problems are not. Any time you want an AI assistant to do the same kind of work repeatedly and stay inside clear boundaries, you run into the same questions. How do you package instructions so they load only when needed? How do you stop the model from “helping” by making things up? How do you chain several tasks so one result feeds the next?
This article walks through how the library is organized and the patterns I think are worth borrowing. If you want to build your own skills library, there is a step-by-step section near the end.
What is a skill?
According to Anthropic’s Agent Skills documentation, a skill is a directory built around an instruction file with YAML frontmatter containing a name and a description. Other files, such as reference documents, scripts, and templates, can sit beside it.
The part that matters architecturally is how skills are loaded. The documentation describes three levels:
- Metadata (name and description) is always available so Claude can decide when a skill is relevant.
- Instructions (the body of the skill file) are read only when the skill is triggered.
- Resources (reference files, scripts) are read only if the instructions point to them and the task needs them.
That is progressive disclosure. It means you can keep detailed rubrics and examples in separate files without paying for them on every conversation. It also explains why a skill’s description deserves real attention: it is the only thing Claude sees until the skill triggers.
The library at a glance
The repository README describes three skills that form a workflow:
- Job Fit Analyzer: scores a complete job posting against verified career evidence, target roles, and constraints. Use it when deciding whether to apply, investigate, or skip.
- Resume Tailor: produces an ATS-readable resume using only approved evidence. Use it once a role has been evaluated and is worth applying to.
- Company Researcher: builds a current, sourced company and role brief. Use it when preparing to apply, network, or interview.
The recommended order is evaluate, then tailor, then research. Each skill is self-contained and follows the same layout:
skill-name/
├── skill.md # definition, workflow, guardrails, output rules
├── README.md # install and usage notes
├── references/ # frameworks, rules, templates, evidence
└── examples/ # strong outputs and prohibited or weak patternsThe consistency is deliberate. When every skill has the same shape, adding a fourth one is mostly a matter of copying the structure and replacing the content.
Design patterns worth borrowing
1. Say when not to use the skill
Each skill.md has a “When to Use” section with typical trigger phrases, but it also says what the skill should not be used for. The Job Fit Analyzer states that it is an evaluation skill and not a resume-writing skill. The Company Researcher says it should not be used primarily to score fit or tailor a resume.
This keeps skills from overlapping. When requests are ambiguous, clear boundaries make it easier for the right skill to be the one that fires.
2. Gate one skill on the output of another
The skills do not simply run in sequence; they check the previous result. The Job Fit Analyzer produces a decision (PRIORITY APPLY, APPLY, INVESTIGATE / NETWORK, or SKIP) using thresholds of 85, 75, and 65. The Resume Tailor then reads that decision: it tailors fully for the first two, pauses on INVESTIGATE / NETWORK until the open issue is resolved, and asks for an explicit override on SKIP. The Company Researcher applies a similar gate and narrows its focus when the decision is still open.
This is a small idea with a large effect. It stops effort from being spent on work that an earlier step already ruled out, and it makes the workflow behave more like a pipeline with quality checks than a set of unrelated prompts.
3. Classify evidence before you score it
The Job Fit Analyzer does not match keywords. It maps each material requirement to evidence and labels it:
- A: direct evidence
- B: supported evidence
- C: transferable evidence
- D: gap
- X: hard conflict
The scoring model then awards a share of each dimension’s points based on the label. For example, A earns roughly 85 to 100 percent of the available credit, C earns roughly 30 to 60 percent, and D earns nothing. There is also an explicit rule that C must never be upgraded to B just to improve a score.
I think this is the most transferable pattern in the repo. Any task where a model judges “how well does X match Y” gets more trustworthy if the judgment is broken into labeled evidence rather than a single impression. The same structure would work for vendor evaluations, proposal reviews, or audit checklists.
4. Define what happens when the input is not enough
A common failure mode is a model producing a confident answer from incomplete material. The Job Fit Analyzer addresses it directly: if only a job title or URL is available and the actual posting cannot be retrieved, it must return this and stop:
STATUS: INSUFFICIENT DATA
Missing:
- Responsibilities
- Required qualifications
- Preferred qualifications
Next input needed:
Paste or attach the complete job description.
Do not generate a fit score.The Resume Tailor has an equivalent STATUS: INPUT REQUIRED. Giving the skill a defined, useful way to refuse is often better than hoping it will say “I’m not sure” on its own.
5. Report confidence separately from the result
The fit score and the confidence in that score are reported independently. A posting can match well and still have low confidence because it is incomplete, and a poor match can have high confidence. Keeping them separate prevents one number from hiding the other, which is a habit I would also want in any engineering report or risk assessment.
6. Teach by negative examples
The examples/ folders are not only “here is a good output.” The Resume Tailor includes a file of prohibited transformations that lists a bad rewrite and the reason it fails. The pattern is: state the bad output, then state why the evidence does not support it. Examples include turning cross-functional coordination into “managed direct reports” or turning deployment coordination into “architected CI/CD platforms.”
Rules tell a model what to avoid; paired bad examples show where the line actually sits.
7. Separate facts from interpretation
The Company Researcher requires current research before any company-specific claim and labels findings as VERIFIED FACT, ROLE SIGNAL, ANALYST INTERPRETATION, or UNKNOWN. A job posting that asks for a technology is treated as a signal about the role, not proof of how the whole company works. Its source rules also rank primary sources (official postings, filings, newsrooms) above secondary and context-only material.
If you build research skills, this labeling is worth copying because it makes a report auditable. A reader can see at a glance which statements to trust, which to question, and which are still open.
8. Make the output auditable
Each skill has an output template. The Resume Tailor goes furthest: it requires an Evidence Trace listing, for every materially changed claim, the final text, the source, the evidence class, the type of change, and a confirmation that no new factual claim was introduced. A bullet that cannot be traced is removed or flagged for confirmation.
For anyone who has dealt with change management, this will feel familiar. It is an audit trail applied to generated text.
How to build your own skills library
Here is a practical path based on the structure above.
1. Start with a workflow, not a prompt
Write down the two or three tasks you repeat and how the output of one feeds the next. Each task becomes a skill.
2. Create one folder per skill with a consistent layout
my-skill/
├── skill.md
├── README.md
├── references/
│ ├── rules.md
│ └── output-template.md
└── examples/
├── good-example.md
└── bad-example.md3. Write the frontmatter carefully
Include a name and a description that says what the skill does and when to use it. Claude relies on the description to decide whether to load the skill.
---
name: my-skill
description: One or two sentences on what this does and when to use it.
---4. Structure the body of skill.md
The skills in this repo follow a pattern you can reuse: Purpose, Authoritative Inputs, When to Use, Workflow (numbered steps), Guardrails, Required Output, and a Quality Gate checklist to run before responding.
5. Move heavy material into references/
Rubrics, scoring tables, and templates belong there, with the main file telling Claude which ones to read and when.
6. Add good and bad examples
Include at least one example of what you do not want.
7. Package and upload
Anthropic’s help article on creating custom skills says the skill folder should be the root of the ZIP, and the folder name should match the skill’s name. From the parent directory:
zip -r my-skill.zip my-skill/Then add the ZIP in Claude under Customize > Skills and enable it. The same article suggests testing with several prompts that should trigger the skill and revising the description if Claude does not use it when expected.
8. Test with realistic inputs
The repo’s per-skill READMEs each include a suggested test prompt, and the Job Fit Analyzer includes calibration cases describing expected behavior. Start with a few cases, including one where the skill should refuse.
Tradeoffs and things to watch
Looking at the repo critically, these are the points I would flag for anyone adapting it:
- Personal evidence belongs in a private place. These skills are built around a document containing career evidence. The repo is public, so if you copy the pattern, decide deliberately what goes into a public repository and what stays private. A shareable version should use sanitized or sample data.
- Duplicated reference files can drift. Each skill is self-contained, so common files such as the career evidence bank are copied into each folder. That makes each ZIP portable, but the copies in this repo are not byte-for-byte identical, which shows how easily duplicates diverge. A single source of truth plus a packaging step would reduce that risk.
- Documentation differs across surfaces. The API-oriented overview documents the main file as
SKILL.mdwith a lowercase-and-hyphensnameand a description limit of 1,024 characters. The help article for claude.ai uses lowercaseskill.mdand states a 200-character description limit. This repo follows the help-article convention and uses readable display names. Check the current documentation for the surface you plan to use before you package anything. - Skills do not sync across surfaces. The overview notes that custom skills need to be uploaded or installed separately for each surface.
- Long instruction files have a cost. Each
skill.mdhere runs roughly 270 to 320 lines. The documentation describes the instruction layer as something that should stay fairly compact. I have not measured token counts, but moving more detail intoreferences/is the natural lever. - Calibration cases are guidance, not automated tests. The repo documents expected behavior but does not include a test harness. If you rely on a skill for decisions, consider building a small set of repeatable test inputs.
What this project taught me
These are the takeaways I would pass on:
- Constraints are as important as capabilities. Most of each skill’s text is about what must not happen.
- Structure turns judgment into something you can inspect: labeled evidence, separate confidence, and an evidence trace.
- A defined refusal path (
INSUFFICIENT DATA) is a feature. - Consistent layout across skills makes a library easy to extend and maintain.
Real-world applications
The job-search domain is incidental. The same structure could support other recurring, evidence-sensitive work, for example:
- Reviewing vendor proposals against a requirements list, with the same A/B/C/D labels.
- Drafting incident postmortems that separate verified timeline facts from interpretation.
- Preparing customer or stakeholder briefs with sourced facts and flagged unknowns.
- Reviewing documents against a checklist, with a required audit trail for every change.
Skills Demonstrated
- AI workflow design: three skills chained by decision gates (the
PRIORITY APPLYtoSKIPoutcomes of the fit skill control the next steps). - Prompt and instruction engineering: purpose, triggers, ordered workflows, and quality gates written into each skill file.
- Quality and risk controls: evidence classification, prohibited-claim lists, and input validation with a defined refusal state.
- Technical documentation: consistent README, reference, template, and example structure across the repository.
- Information architecture: separating instructions from references and examples to support progressive loading.
- Repository management: a public GitHub repository with an Apache 2.0 license.
Conclusion
A skills library is less about clever prompts and more about the engineering around them: clear boundaries, structured evidence, defined failure states, and outputs you can audit. The job-search skills in ai-skills are one example of those ideas. If you try the pattern on your own workflow, I would start small with one skill, one rubric, and one bad example, then grow from there.
References
- Ravi Baghel, ai-skills (GitHub repository)
- Anthropic, Agent Skills overview
- Anthropic Help Center, Creating custom skills
- ai-skills, Apache License 2.0 (repository LICENSE)
This article was written based on my hands-on learning and technical exploration, with AI assistance used for content organization, editing, and clarity.
